--- warn: This is just a prototype. --- # 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][RST]. ## Table of Contents [TOC] ## 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 ### `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`. ### `taget_namespace` Indicates that the elements defined by this schema come from the specified URL namespace. Optional. ### `xmlns` Indicates that the default namespace is the specified URL. Mandatory. ### `schemaLocation` 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) - Element names can contain letters, digits, hyphens, underscores, and periods - 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: | type | children elements | text node | attributes | |------------|:-----------------:|:---------:|:----------:| |simple | ✗ | ✓ | ✗ | |empty | ✗ | ✗ | ✓ | |no_text | ✓ | ✗ | ✓ | |no_elements | ✗ | ✓ | ✓ | |mixed | ✓ | ✓ | ✓ | > **Note**: attributes are never mandatory; they could be zero or more. ### `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. ### `fixed` Indicates fixed value to element or attribute. Optional. ### `use` Indicates that the attribute is required. Optional. Only `required` is valid as value. ### `restriction` 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. - `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`. ### `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: - `true`. - `false`. ### `elements` Indicates elements for schema. Mandatory. ### `attributes` Indicates attributes for schema. Optional. ### `schema` Indicates schema general information. Mandatory. ## References * “XSD Tutorial”, [Tutorials Point]. * “XML Schema Tutorial”, [W3Schools]. [YASD]: https://gitlab.com/amlengua/apal/esquema/-/blob/main/apal.yaml [XSD]: https://gitlab.com/amlengua/apal/esquema/-/blob/main/apal.xsd [RST]: https://gitlab.com/amlengua/apal/esquema/-/blob/main/apal.rst [Tutorials Point]: https://www.tutorialspoint.com/xsd/ [W3Schools]: https://www.w3schools.com/xml/schema_intro.asp