441 lines
12 KiB
Markdown
441 lines
12 KiB
Markdown
# 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="?" />`.
|
||
|
||
## CLI Workflow
|
||
|
||
The following chart is the YASD CLI workflow:
|
||
|
||
``` 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| RST([reStructuredText])
|
||
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 [reStructuredText].
|
||
|
||
## Table of Contents
|
||
|
||
\[TOC\]
|
||
|
||
## Structure
|
||
|
||
### General Structure
|
||
|
||
schema:
|
||
SCHM
|
||
elements:
|
||
- ELMT
|
||
...
|
||
attributeElements:
|
||
- 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
|
||
attributes:
|
||
- ref: attribute_name
|
||
use: optional|required|prohibited
|
||
- group: group_name
|
||
...
|
||
children_order: all|choice|sequence
|
||
children:
|
||
- ref: element_name
|
||
maxOccurs: INTEGER|unbounded
|
||
minOccurs: INTEGER
|
||
- group: group_name
|
||
maxOccurs: INTEGER|unbounded
|
||
minOccurs: INTEGER
|
||
remove:
|
||
- element_or_attribute_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
|
||
restriction:
|
||
- CONSTRAIN
|
||
...
|
||
|
||
### Group (GRPS) Structure
|
||
|
||
name: group_name
|
||
attribute_group: true|false
|
||
children_order: all|choice|sequence
|
||
children:
|
||
- ref: element_or_attribute_name
|
||
maxOccurs: INTEGER|unbounded
|
||
minOccurs: INTEGER
|
||
|
||
## Key Reference
|
||
|
||
### `attribute_group`
|
||
|
||
Indicates if group is an attribute group.
|
||
|
||
Optional; if not present by default is `false`.
|
||
|
||
Allowed values:
|
||
|
||
- `true`.
|
||
- `false`.
|
||
|
||
### `attributeElements`
|
||
|
||
Indicates attributes elements for schema.
|
||
|
||
Optional.
|
||
|
||
### `attributes`
|
||
|
||
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.
|
||
|
||
### `datatype`
|
||
|
||
Indicates element or attribute data types.
|
||
|
||
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).
|
||
- `IDREF`. A string that represents the IDREF attribute in XML (only used
|
||
with schema attributes).
|
||
- `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.
|
||
|
||
Only allowed for simple elements or attributes.
|
||
|
||
### `description`
|
||
|
||
Indicates element or attribute description in human readable form.
|
||
|
||
Optional.
|
||
|
||
### `elementFormDefault`
|
||
|
||
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`.
|
||
|
||
### `elements`
|
||
|
||
Indicates elements for schema.
|
||
|
||
Mandatory.
|
||
|
||
### `fixed`
|
||
|
||
Indicates fixed value to element or attribute.
|
||
|
||
Optional; ignored if 'default' is present.
|
||
|
||
Only allowed for simple elements or attributes.
|
||
|
||
### `group`
|
||
|
||
References group name.
|
||
|
||
Optional.
|
||
|
||
### `groups`
|
||
|
||
Indicates element or attribute groups for schema.
|
||
|
||
Optional.
|
||
|
||
### `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.
|
||
|
||
### `name`
|
||
|
||
Indicates element, attribute or group 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)
|
||
- Element names can contain letters, digits and underscores
|
||
- Element names cannot contain spaces or hyphens
|
||
|
||
### `ref`
|
||
|
||
References element or attribute by name.
|
||
|
||
Mandatory.
|
||
|
||
### `remove`
|
||
|
||
Removes element or attribute from group by name.
|
||
|
||
Optional.
|
||
|
||
### `restriction`
|
||
|
||
Indicates accepted constrained values for attribute.
|
||
|
||
Optional; if present, must contain at least one constrain and attribute
|
||
`datatype` is ignored.
|
||
|
||
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.
|
||
- `totalDigits`. Specifies the exact number of digits allowed; must be
|
||
greater than zero.
|
||
- `whiteSpace`. Specifies how white space (line feeds, tabs, spaces, and
|
||
carriage returns) is handled; accepted values are
|
||
`preserve|replace|collapse`.
|
||
|
||
### `schema`
|
||
|
||
Indicates schema general information.
|
||
|
||
Mandatory.
|
||
|
||
### `schemaLocation`
|
||
|
||
Indicates the location of the XML schema to use for that namespace.
|
||
|
||
Optional.
|
||
|
||
### `taget_namespace`
|
||
|
||
Indicates that the elements defined by this schema come from the specified URL
|
||
namespace.
|
||
|
||
Optional.
|
||
|
||
### `type`
|
||
|
||
Indicates element type.
|
||
|
||
Mandatory.
|
||
|
||
Allowed types:
|
||
|
||
- `simple`. Only text node allowed.
|
||
- `empty`. Only attributes allowed.
|
||
- `no_text`. No children text nodes allowed.
|
||
- `no_elements`. No children elements allowed.
|
||
- `mixed`. Children elements, text node and attributes allowed.
|
||
|
||
Chart:
|
||
|
||
| type | elements | text | attributes |
|
||
|-------------|:--------:|:----:|:----------:|
|
||
| simple | ✗ | ✓ | ✗ |
|
||
| empty | ✗ | ✗ | ✓ |
|
||
| no_text | ✓ | ✗ | ✓ |
|
||
| no_elements | ✗ | ✓ | ✓ |
|
||
| mixed | ✓ | ✓ | ✓ |
|
||
|
||
> **Note 1**: read "elements" and "text" with "direct children..." as prefix.
|
||
|
||
> **Note 2**: attributes are never mandatory; they could be zero or more.
|
||
|
||
### `use`
|
||
|
||
Indicates that the attribute is required.
|
||
|
||
Optional; if not present by default is `optional`.
|
||
|
||
Allowed uses:
|
||
|
||
- `optional`.
|
||
- `required`.
|
||
- `prohibited`.
|
||
|
||
### `version`
|
||
|
||
Indicates XML schema version.
|
||
|
||
Mandatory.
|
||
|
||
### `xmlns`
|
||
|
||
Indicates that the default namespace is the specified URL.
|
||
|
||
Mandatory.
|
||
|
||
## References
|
||
|
||
- "XML Schema Reference", [W3ref]
|
||
- "XML Schema Tutorial", [W3Schools].
|
||
- "XSD Tutorial", [Tutorials Point].
|
||
|
||
## License
|
||
|
||
YASD is under GPLv3, check the license terms [here].
|
||
|
||
## Acknowledgments
|
||
|
||
YASD is founded by [Mexican Academy of Language].
|
||
|
||
## License
|
||
|
||
YASD is under GPLv3, check the license terms \[here\]
|
||
|
||
[YASD]: https://gitlab.com/amlengua/apal/esquema/-/blob/main/apal.yaml
|
||
[XSD]: https://gitlab.com/amlengua/apal/esquema/-/blob/main/apal.xsd
|
||
[reStructuredText]: https://gitlab.com/amlengua/apal/esquema/-/blob/main/apal.rst
|
||
[W3ref]: https://www.w3schools.com/xml/schema_elements_ref.asp
|
||
[W3Schools]: https://www.w3schools.com/xml/schema_intro.asp
|
||
[Tutorials Point]: https://www.tutorialspoint.com/xsd/
|
||
[here]: https://git.cuates.net/perro/yasd/src/branch/no-masters/LICENSE.md
|
||
[Mexican Academy of Language]: https://academia.org.mx
|