2023-01-25 19:59:39 -06:00
|
|
|
|
# YASD, Yet Another Schema Definition
|
|
|
|
|
|
|
|
|
|
YASD is a YAML format for human writable XSDs (XML Schema Definition), humans
|
|
|
|
|
declare what is indispensable, leaving the machines to do the rest of the
|
|
|
|
|
unreadable `<syntaxis who_can_read_this="?" />`.
|
|
|
|
|
|
2023-01-25 21:33:39 -06:00
|
|
|
|
## CLI Workflow
|
2023-01-25 21:30:33 -06:00
|
|
|
|
|
2023-01-25 21:33:39 -06:00
|
|
|
|
The following chart is the YASD CLI workflow:
|
2023-01-25 21:30:33 -06:00
|
|
|
|
|
|
|
|
|
``` mermaid
|
|
|
|
|
flowchart LR
|
|
|
|
|
direction LR
|
|
|
|
|
yasd --- convert
|
|
|
|
|
yasd --- check
|
|
|
|
|
yasd --- sample
|
|
|
|
|
yasd --- document
|
|
|
|
|
yasd --- man
|
|
|
|
|
convert --- |from| YASD1([YASD])
|
|
|
|
|
YASD1 --> |to| XSD([XSD])
|
|
|
|
|
check --- |validates| YASD2([YASD])
|
|
|
|
|
sample --- |from| YASD3([YASD])
|
|
|
|
|
YASD3 --> |to| XML([XML])
|
|
|
|
|
document --- |from| YASD4([YASD])
|
|
|
|
|
YASD4 --> |to| MD([Markdown])
|
|
|
|
|
man --- |prints| README
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Example
|
|
|
|
|
|
|
|
|
|
To better understad what YASD does, see the inputs and outputs:
|
|
|
|
|
|
|
|
|
|
- Input: human workable schema in [YASD].
|
|
|
|
|
- Output: computer processable schema in [XSD].
|
|
|
|
|
- Output: human readable documentation in [Markdown].
|
|
|
|
|
|
2023-01-25 21:33:39 -06:00
|
|
|
|
## Table of Contents
|
|
|
|
|
|
2023-01-25 21:32:00 -06:00
|
|
|
|
[TOC]
|
|
|
|
|
|
2023-01-25 19:59:39 -06:00
|
|
|
|
## Structure
|
|
|
|
|
|
|
|
|
|
General structure:
|
|
|
|
|
|
|
|
|
|
schema:
|
|
|
|
|
SCHM
|
|
|
|
|
elements:
|
|
|
|
|
- ELMT
|
|
|
|
|
...
|
|
|
|
|
attributes:
|
|
|
|
|
- ATTR
|
|
|
|
|
...
|
|
|
|
|
groups:
|
|
|
|
|
- GRPS
|
|
|
|
|
|
|
|
|
|
Schema (SCHM) structure:
|
|
|
|
|
|
|
|
|
|
elementFormDefault: qualified|unqualified
|
|
|
|
|
targetNamespace: http://a.link
|
|
|
|
|
xmlns: http://a.link
|
|
|
|
|
schemaLocation: http://a-link-to.xsd
|
|
|
|
|
version: 0.1
|
|
|
|
|
|
|
|
|
|
Element (ELMT) structure:
|
|
|
|
|
|
|
|
|
|
name: element_name
|
|
|
|
|
description: Element description
|
|
|
|
|
type: simple|empty|no_text|no_elements|mixed
|
|
|
|
|
datatype: string|integer|decimal|date|time|language|duration|token|boolean|byte|int|double|float|long|short|normalizedString|dateTime|gDay|gMonth|gMonthDay|gYear|gYearMonth|negativeInteger|nonNegativeInteger|nonPositiveInteger|positiveInteger|unsignedLong|unsignedInt|unsignedShort|unsignedByte|anyURI|base64Binary|hexBinary|Name|QName|NCName|ID|IDREF|IDREFS|ENTITY|ENTITIES|NMTOKEN|NMTOKENS|NOTATION
|
|
|
|
|
default: a_value
|
|
|
|
|
fixed: a_value
|
|
|
|
|
restriction:
|
|
|
|
|
CONSTRAIN
|
|
|
|
|
...
|
|
|
|
|
attribute:
|
|
|
|
|
- attribute_name
|
|
|
|
|
...
|
|
|
|
|
children_order: all|choice|sequence
|
|
|
|
|
children:
|
|
|
|
|
- name: element_name
|
|
|
|
|
maxOccurs: INTEGER
|
|
|
|
|
minOccurs: INTEGER
|
|
|
|
|
- group: group_name
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
Attribute (ATTR) structure:
|
|
|
|
|
|
|
|
|
|
name: attribute_name
|
|
|
|
|
description: Attribute description
|
|
|
|
|
datatype: string|integer|decimal|date|time|language|duration|token|boolean|byte|int|double|float|long|short|normalizedString|dateTime|gDay|gMonth|gMonthDay|gYear|gYearMonth|negativeInteger|nonNegativeInteger|nonPositiveInteger|positiveInteger|unsignedLong|unsignedInt|unsignedShort|unsignedByte|anyURI|base64Binary|hexBinary|Name|QName|NCName|ID|IDREF|IDREFS|ENTITY|ENTITIES|NMTOKEN|NMTOKENS|NOTATION
|
|
|
|
|
default: a_value
|
|
|
|
|
fixed: a_value
|
|
|
|
|
use: required
|
|
|
|
|
restriction:
|
|
|
|
|
CONSTRAIN
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
Group (GRPS) structure:
|
|
|
|
|
|
|
|
|
|
name: group_name
|
|
|
|
|
attribute_group: true|false
|
|
|
|
|
children_order: all|choice|sequence
|
|
|
|
|
children:
|
|
|
|
|
- name: element_name
|
|
|
|
|
maxOccurs: INTEGER|unbounded
|
|
|
|
|
minOccurs: INTEGER
|
|
|
|
|
|
|
|
|
|
## Reference
|
|
|
|
|
|
2023-01-25 21:38:25 -06:00
|
|
|
|
### `elementFormDefault`
|
2023-01-25 19:59:39 -06:00
|
|
|
|
|
|
|
|
|
Indicates that any elements used by the XML instance document which were
|
|
|
|
|
declared in this schema must be namespace qualified.
|
|
|
|
|
|
|
|
|
|
Optional; if not present by default is `unqualified`.
|
|
|
|
|
|
2023-01-25 21:38:25 -06:00
|
|
|
|
### `taget_namespace`
|
2023-01-25 19:59:39 -06:00
|
|
|
|
|
|
|
|
|
Indicates that the elements defined by this schema come from the specified URL
|
|
|
|
|
namespace.
|
|
|
|
|
|
|
|
|
|
Optional.
|
|
|
|
|
|
2023-01-25 21:38:25 -06:00
|
|
|
|
### `xmlns`
|
2023-01-25 19:59:39 -06:00
|
|
|
|
|
|
|
|
|
Indicates that the default namespace is the specified URL.
|
|
|
|
|
|
|
|
|
|
Mandatory.
|
|
|
|
|
|
2023-01-25 21:38:25 -06:00
|
|
|
|
### `schemaLocation`
|
2023-01-25 19:59:39 -06:00
|
|
|
|
|
|
|
|
|
Indicates the location of the XML schema to use for that namespace.
|
|
|
|
|
|
|
|
|
|
Optional.
|
|
|
|
|
|
|
|
|
|
### `version`
|
|
|
|
|
|
|
|
|
|
Indicates XML schema version.
|
|
|
|
|
|
|
|
|
|
Mandatory.
|
|
|
|
|
|
|
|
|
|
### `name`
|
|
|
|
|
|
|
|
|
|
Indicates element or attribute name.
|
|
|
|
|
|
|
|
|
|
Mandatory.
|
|
|
|
|
|
|
|
|
|
For elements, its name is commonly known as tag name.
|
|
|
|
|
|
|
|
|
|
Naming rules:
|
|
|
|
|
|
|
|
|
|
- Element names are case-sensitive
|
|
|
|
|
- Element names must start with a letter or underscore
|
|
|
|
|
- Element names cannot start with the letters xml (or XML, or Xml, etc)
|
2023-01-25 21:30:33 -06:00
|
|
|
|
- Element names can contain letters, digits, hyphens, underscores, and
|
|
|
|
|
periods
|
2023-01-25 19:59:39 -06:00
|
|
|
|
- Element names cannot contain spaces
|
|
|
|
|
|
|
|
|
|
### `description`
|
|
|
|
|
|
|
|
|
|
Indicates element or attribute description in human readable form.
|
|
|
|
|
|
|
|
|
|
Optional.
|
|
|
|
|
|
|
|
|
|
### `type`
|
|
|
|
|
|
|
|
|
|
Indicates element type.
|
|
|
|
|
|
|
|
|
|
Mandatory.
|
|
|
|
|
|
|
|
|
|
Allowed types:
|
|
|
|
|
|
|
|
|
|
- `simple`. Only text node allowed.
|
|
|
|
|
- `empty`. Only attributes allowed.
|
|
|
|
|
- `no_text`. No text nodes allowed.
|
|
|
|
|
- `no_elements`. No children elements allowed.
|
|
|
|
|
- `mixed`. Children elements, text node and attributes allowed.
|
|
|
|
|
|
|
|
|
|
Chart:
|
|
|
|
|
|
2023-01-25 21:30:33 -06:00
|
|
|
|
| type | children elements | text node | attributes |
|
|
|
|
|
|------------|:-----------------:|:---------:|:----------:|
|
|
|
|
|
|simple | ā | ā | ā |
|
|
|
|
|
|empty | ā | ā | ā |
|
|
|
|
|
|no_text | ā | ā | ā |
|
|
|
|
|
|no_elements | ā | ā | ā |
|
|
|
|
|
|mixed | ā | ā | ā |
|
2023-01-25 19:59:39 -06:00
|
|
|
|
|
|
|
|
|
> **Note**: attributes are never mandatory; they could be zero or more.
|
|
|
|
|
|
|
|
|
|
### `datatype`
|
|
|
|
|
|
2023-01-25 21:38:25 -06:00
|
|
|
|
Indicates element or attribute data types.
|
2023-01-25 19:59:39 -06:00
|
|
|
|
|
|
|
|
|
Only mandatory for 'simple' and 'no_elements' elements, and attributes.
|
|
|
|
|
|
|
|
|
|
Allowed String Data Types:
|
|
|
|
|
|
|
|
|
|
- `ENTITIES`. Ā
|
|
|
|
|
- `ENTITY`. Ā
|
|
|
|
|
- `ID`. A string that represents the ID attribute in XML (only used with
|
|
|
|
|
schema attributes).
|
2023-01-25 21:30:33 -06:00
|
|
|
|
- `IDREF`. A string that represents the IDREF attribute in XML (only used
|
|
|
|
|
with schema attributes).
|
2023-01-25 19:59:39 -06:00
|
|
|
|
- `IDREFS`.
|
|
|
|
|
- `language`. A string that contains a valid language id.
|
|
|
|
|
- `Name`. A string that contains a valid XML name.
|
|
|
|
|
- `NCName`.
|
|
|
|
|
- `NMTOKEN`. A string that represents the NMTOKEN attribute in XML (only used
|
|
|
|
|
with schema attributes).
|
|
|
|
|
- `NMTOKENS`.
|
|
|
|
|
- `normalizedString`. A string that does not contain line feeds, carriage
|
|
|
|
|
returns, or tabs.
|
|
|
|
|
- `QName`.
|
|
|
|
|
- `string`. A string.
|
|
|
|
|
- `token`. A string that does not contain line feeds, carriage returns, tabs,
|
|
|
|
|
leading or trailing spaces, or multiple spaces.
|
|
|
|
|
|
|
|
|
|
Allowed Date and Time Data Types:
|
|
|
|
|
|
|
|
|
|
- `date`. Defines a date value.
|
|
|
|
|
- `dateTime`. Defines a date and time value.
|
|
|
|
|
- `duration`. Defines a time interval.
|
|
|
|
|
- `gDay`. Defines a part of a date - the day (DD).
|
|
|
|
|
- `gMonth`. Defines a part of a date - the month (MM).
|
|
|
|
|
- `gMonthDay`. Defines a part of a date - the month and day (MM-DD).
|
|
|
|
|
- `gYear`. Defines a part of a date - the year (YYYY).
|
|
|
|
|
- `gYearMonth`. Defines a part of a date - the year and month (YYYY-MM).
|
|
|
|
|
- `time`. Defines a time value.
|
|
|
|
|
|
|
|
|
|
Allowed Numeric Data Types:
|
|
|
|
|
|
|
|
|
|
- `byte`. A signed 8-bit integer.
|
|
|
|
|
- `decimal`. A decimal value.
|
|
|
|
|
- `int`. A signed 32-bit integer.
|
|
|
|
|
- `integer`. An integer value.
|
|
|
|
|
- `long`. A signed 64-bit integer.
|
|
|
|
|
- `negativeInteger`. An integer containing only negative values (..,-2,-1).
|
|
|
|
|
- `nonNegativeInteger`. An integer containing only non-negative values
|
|
|
|
|
(0,1,2,..).
|
|
|
|
|
- `nonPositiveInteger`. An integer containing only non-positive values
|
|
|
|
|
(..,-2,-1,0).
|
|
|
|
|
- `positiveInteger`. An integer containing only positive values (1,2,..).
|
|
|
|
|
- `short`. A signed 16-bit integer.
|
|
|
|
|
- `unsignedLong`. An unsigned 64-bit integer.
|
|
|
|
|
- `unsignedInt`. An unsigned 32-bit integer.
|
|
|
|
|
- `unsignedShort`. An unsigned 16-bit integer.
|
|
|
|
|
- `unsignedByte`. An unsigned 8-bit integer.
|
|
|
|
|
|
|
|
|
|
Allowed Miscellaneous Data Types:
|
|
|
|
|
|
|
|
|
|
- `anyURI`.
|
|
|
|
|
- `base64Binary`.
|
|
|
|
|
- `boolean`.
|
|
|
|
|
- `double`.
|
|
|
|
|
- `float`.
|
|
|
|
|
- `hexBinary`.
|
|
|
|
|
- `NOTATION`.
|
|
|
|
|
- `QName`.
|
|
|
|
|
|
|
|
|
|
### `default`
|
|
|
|
|
|
|
|
|
|
Indicates default value when element or attribute is empty.
|
|
|
|
|
|
|
|
|
|
Optional.
|
|
|
|
|
|
|
|
|
|
### `fixed`
|
|
|
|
|
|
|
|
|
|
Indicates fixed value to element or attribute.
|
|
|
|
|
|
|
|
|
|
Optional.
|
|
|
|
|
|
|
|
|
|
### `use`
|
|
|
|
|
|
|
|
|
|
Indicates that the attribute is required.
|
|
|
|
|
|
|
|
|
|
Optional.
|
|
|
|
|
|
|
|
|
|
Only `required` is valid as value.
|
|
|
|
|
|
2023-01-25 21:38:25 -06:00
|
|
|
|
### `restriction`
|
2023-01-25 19:59:39 -06:00
|
|
|
|
|
|
|
|
|
Indicates accepted constrained values for element or attribute.
|
|
|
|
|
|
|
|
|
|
Optional; if present, must contain at least one constrain.
|
|
|
|
|
|
|
|
|
|
Not allowed for 'empty' and 'no_text' elements.
|
|
|
|
|
|
|
|
|
|
Allowed constrains:
|
|
|
|
|
|
|
|
|
|
- `enumeration`. Specifies a list of acceptable values.
|
|
|
|
|
- `fractionDigits`. Specifies the maximum number of decimal places allowed;
|
|
|
|
|
must be equal to or greater than zero.
|
|
|
|
|
- `length`. Specifies the exact number of characters or list items allowed;
|
|
|
|
|
must be equal to or greater than zero.
|
|
|
|
|
- `maxExclusive`. Specifies the upper bounds for numeric values (the value
|
|
|
|
|
must be less than this value).
|
|
|
|
|
- `maxInclusive`. Specifies the upper bounds for numeric values (the value
|
|
|
|
|
must be less than or equal to this value).
|
|
|
|
|
- `maxLength`. Specifies the maximum number of characters or list items
|
|
|
|
|
allowed; must be equal to or greater than zero.
|
|
|
|
|
- `minExclusive`. Specifies the lower bounds for numeric values (the value
|
|
|
|
|
must be greater than this value).
|
|
|
|
|
- `minInclusive`. Specifies the lower bounds for numeric values (the value
|
|
|
|
|
must be greater than or equal to this value).
|
|
|
|
|
- `minLength`. Specifies the minimum number of characters or list items
|
|
|
|
|
allowed; must be equal to or greater than zero.
|
|
|
|
|
- `pattern`. Defines the exact sequence of characters that are acceptable.
|
2023-01-25 21:30:33 -06:00
|
|
|
|
- `totalDigits`. Specifies the exact number of digits allowed; must be
|
|
|
|
|
greater than zero.
|
2023-01-25 19:59:39 -06:00
|
|
|
|
- `whiteSpace`. Specifies how white space (line feeds, tabs, spaces, and
|
|
|
|
|
carriage returns) is handled; accepted values are
|
|
|
|
|
`preserve|replace|collapse`.
|
|
|
|
|
|
|
|
|
|
### `attribute`
|
|
|
|
|
|
|
|
|
|
Indicates a list of attributes for an element.
|
|
|
|
|
|
|
|
|
|
### `children_order`
|
|
|
|
|
|
|
|
|
|
Indicates order indicators for children elements.
|
|
|
|
|
|
|
|
|
|
Mandatory in `no_text` or `mixed` elements, and group.
|
|
|
|
|
|
|
|
|
|
Allowed values:
|
|
|
|
|
|
|
|
|
|
- `all`. Children elements can occur in any order.
|
|
|
|
|
- `choice`. Only one children element can accur.
|
|
|
|
|
- `sequence`. Children elements must occur in specified order.
|
|
|
|
|
|
|
|
|
|
### `children`
|
|
|
|
|
|
|
|
|
|
Indicates a list of children elements.
|
|
|
|
|
|
|
|
|
|
Mandatory in `no_text` or `mixed` elements, and group.
|
|
|
|
|
|
|
|
|
|
### `maxOccurs`
|
|
|
|
|
|
|
|
|
|
Indicates max number of times a children element can accur.
|
|
|
|
|
|
|
|
|
|
Optional; if not present by default is `1`.
|
|
|
|
|
|
|
|
|
|
Valid values are non negative integer or `unbounded` for unlimited number of
|
|
|
|
|
times.
|
|
|
|
|
|
|
|
|
|
### `minOccurs`
|
|
|
|
|
|
|
|
|
|
Indicates min number of times a children element can accur.
|
|
|
|
|
|
|
|
|
|
Optional; if not present by default is `1`.
|
|
|
|
|
|
|
|
|
|
Valid value is non negative integer.
|
|
|
|
|
|
|
|
|
|
### `group`
|
|
|
|
|
|
|
|
|
|
Indicates group name.
|
|
|
|
|
|
|
|
|
|
Optional.
|
|
|
|
|
|
|
|
|
|
### `groups`
|
|
|
|
|
|
|
|
|
|
Indicates element or attribute groups for schema.
|
|
|
|
|
|
|
|
|
|
Optional.
|
|
|
|
|
|
|
|
|
|
### `attribute_group`
|
|
|
|
|
|
|
|
|
|
Indicates if group is an attribute group.
|
|
|
|
|
|
|
|
|
|
Optional; if not present by default is `false`.
|
|
|
|
|
|
|
|
|
|
Allowed values:
|
|
|
|
|
|
2023-01-25 21:30:33 -06:00
|
|
|
|
- `true`.
|
|
|
|
|
- `false`.
|
2023-01-25 19:59:39 -06:00
|
|
|
|
|
|
|
|
|
### `elements`
|
|
|
|
|
|
|
|
|
|
Indicates elements for schema.
|
|
|
|
|
|
|
|
|
|
Mandatory.
|
|
|
|
|
|
|
|
|
|
### `attributes`
|
|
|
|
|
|
|
|
|
|
Indicates attributes for schema.
|
|
|
|
|
|
|
|
|
|
Optional.
|
|
|
|
|
|
|
|
|
|
### `schema`
|
|
|
|
|
|
|
|
|
|
Indicates schema general information.
|
|
|
|
|
|
|
|
|
|
Mandatory.
|
|
|
|
|
|
2023-01-25 21:30:33 -06:00
|
|
|
|
[YASD]: https://gitlab.com/amlengua/apal/esquema/-/blob/main/apal.yaml
|
|
|
|
|
[XSD]: https://gitlab.com/amlengua/apal/esquema/-/blob/main/apal.xsd
|
|
|
|
|
[Markdown]: https://gitlab.com/amlengua/apal/esquema/-/blob/main/apal.md
|