A proposal for extensible YAML directives
The YAML 1.1 working draft dated 2004-12-28 in section 4.3.1 Directives, says:
"There is no way to define private directives. This is intentional."
but then goes on to say:
"A YAML processor should ignore unknown directives with an appropriate warning."
Previous experience suggests is a dangerous combination! Long term, it is safer to forbid an extension
mechanism entirely, or to allow for it and define a mechanism for identifying which extensions
directives may be safely ignored. My preference would be for the later.
Here we can borrow from tagged data formats, such as PNG http://www.libpng.org/pub/png/
<http://www.libpng.org/pub/png/> , which use an initial lower-case letters to indicate if a tagged
value can be safely ignored. YAML should do the same, but since we aren't limited to PNG's 4-byte chunk
types, YAML directive names should be URIs! A YAML parser could safely ignore (and/or pass to
higher-levels) any directive that started with a lower-case letter, for example:
%YAML 1.1
%title The "Lost" Numbers
---
[ 4, 8, 15, 16, 23, 42 ]
where the %title directive could be treated as a metatadata, or simply a tagged comment. On the other hand, a
YAML processor should treat as an error any unrecognized directive starting with an upper-case letter,
for example:
%YAML 1.1
%HTTP://WWW.CONTOSO.COM/ATSIGN_INCLUDE
---
[ 4, 8, 15, <at> last3numbers.yaml ]
where the private directive might (for example) indicate a proprietary YAML extension which gives some
specific meaning to the otherwise-reserved ' <at> ' indicator. Since the first character of the directive
name ('H') is not lower-case, any YAML processor unsure of its meaning should refuse to process the document.
Treating directive names as URIs allows use of any of the available URI mechanisms to ensure uniqueness.
Directives without a URI scheme delimiter (':') would be treated as relative URIs based on
"tag:yaml.org,2005:", where we would maintain a "directives repository" parallel to the existing
"types catalog". Determination if a directive is ignorable or not should be done prior to relative URI processing.
I would further propose directive names be reserved in the tag:yaml.org,2005: "directive repository":
# The YAML 1.1 directives MUST be understood
- YAML <int>.<int>
- TAG <handle> <uri-prefix>
# Ignorable metadata directive to identify the
# software name and version which generated
# the YAML document, expressed as a URI.
- generator <uri>
# Ignorable metadata based on the Dublin Core,
# see http://dublincore.org/documents/2004/12/20/dces/
- title <scalar>
- creator <scalar>
- subject <scalar>
- description <scalar>
- publisher <scalar>
- contributor <scalar>
- date <iso 8601>
- type <uri>
- format <mime-type>
- identifier <scalar>
- source <scalar>
- language <rfc-3066_iso639>
- relation <scalar>
- coverage <scalar>
- rights <scalar>
There are at least a couple open issues in my mind:
Folding of parameters:
It may be desirable to allow directive parameters to be
folded using indentation, rather than limited to a single
line, but this could cause compatibility issues.
Context where directives may appear:
I believe the current draft only allows directives at the
beginning of a document. I could imagine cases where such an
extension mechanism could be valuable inside a YAML document.
I hope this proposal is clear and useful. I look forward to your feedback...
-------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc. Do you grep through log files
for problems? Stop! Download the new AJAX search engine that makes
searching your log files as easy as surfing the web. DOWNLOAD SPLUNK!
http://ads.osdn.com/?ad_idv37&alloc_id865&op=click
RSS Feed