11 KiB
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:
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:
- name: attribute_name
- group: group_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 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.
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.
fixed
Indicates fixed value to element or attribute.
Optional; ignored if 'default' is present.
Only allowed for simple elements or attributes.
use
Indicates that the attribute is required.
Optional.
Only required
is valid as value.
restriction
Indicates accepted constrained values for attribute.
Optional; if present, must contain at least one constrain.
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 arepreserve|replace|collapse
.
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.
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.
attributeElements
Indicates attributes elements for schema.
Optional.
schema
Indicates schema general information.
Mandatory.
References
- "XML Schema Reference", W3ref
- "XML Schema Tutorial", W3Schools.
- "XSD Tutorial", Tutorials Point.