# 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 ``. ## 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