Draft
Community
Group
Report
02
Copyright © 2020-2024 the Contributors to the YAML-LD Specification, published by the JSON for Linking Data Community Group under the W3C Community Contributor License Agreement (CLA) . A human-readable summary is available.
Objective
This
document
defines
YAML-LD,
a
set
of
conventions
built
on
top
of
YAML,
which
outlines
how
to
serialize
Linked
Data
as
YAML
based
on
JSON-LD
syntax,
semantics,
and
APIs.
The
emergence
of
YAML
as
a
more
concise
format
for
representing
information
previously
serialized
as
JSON,
including
Linked
Data,
has
led
to
the
development
of
YAML-LD.
Methods
This
document
defines
constraints
on
YAML
so
that
any
YAML-LD
document
can
be
represented
in
JSON-LD.
This
is
necessary
because
YAML
is
more
expressive
than
JSON,
in
terms
of
both
available
data
types
and
document
structure.
This
document
also
registers
the
application/ld+yaml
media
type.
Results
This
document
provides
a
clear
description
of
how
to
serialize
Linked
Data
in
YAML.
It
also
describes
the
basic
concepts
and
core
requirements
for
implementing
YAML-LD,
including
a
comparison
of
JSON
versus
YAML,
the
supported
YAML
features,
and
encoding
considerations.
Limitations
The
YAML
feature
set
is
richer
than
that
of
JSON,
and
a
number
of
YAML
features
are
not
supported
in
this
specification.
However,
ground
is
laid
for
future
development
of
a
version
of
YAML-LD
which
will
support
those
features
—
via
the
Extended
YAML-LD
Profile.
Conclusions
YAML-LD
offers
an
efficient
way
to
encode
Linked
Data
in
a
variety
of
programming
languages
which
can
use
YAML.
An introductory YAML-LD example is presented below.
"@context":
- https://json-ld.org/contexts/dollar-convenience.jsonld
- "@base": https://json-ld.github.io/yaml-ld/spec/
rdfs: http://www.w3.org/2000/01/rdf-schema#
schema: https://schema.org/
license:
"@type": "@id"
$id: https://json-ld.github.io/yaml-ld/spec/
rdfs:label: YAML-LD
license: https://spdx.org/licenses/W3C.html
schema:hasPart:
- rdfs:label: Abstract
- rdfs:label: Status of This Document
-
rdfs:label:
Introduction
This specification was published by the JSON for Linking Data Community Group . It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups .
This document has been developed by the JSON-LD Community Group .
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-linked-json@w3.org ( subscribe , archives ).
[ JSON-LD11 ] is a JSON-based format to serialize Linked Data. In recent years, [ YAML ] has emerged as a more concise format to represent information that had previously been serialized as [ JSON ], including API specifications, data schemas, and Linked Data.
This document defines YAML-LD as a set of conventions on top of YAML which specify how to serialize Linked Data [ LINKED-DATA ] as [ YAML ] based on JSON-LD syntax, semantics, and APIs.
Since YAML is more expressive than JSON, both in the available data types and in the document structure (see [ I-D.ietf-httpapi-yaml-mediatypes ]), this document identifies constraints on YAML such that any YAML-LD document can be represented in JSON-LD.
spec.yaml
.
This section is non-normative.
To understand the basics of this specification, one must be familiar with the following:
This document is intended primarily for two main audiences, as described below.
Among related technologies, JSON-LD familiarity would be required to build most YAML-LD capable applications, while RDF familiarity is only required when it is desired to convert YAML-LD to RDF graphs, or vice versa.
Other professionals, both IT and otherwise who want to read and/or produce Linked Data documents in YAML-LD format. Such documents can be —
For these users, familiarity with JSON-LD is not required, but understanding of Linked Data principles might be beneficial.
This section is non-normative.
This document uses the following terms as defined in external specifications and defines terms specific to JSON-LD.
A YAML-LD stream is a YAML stream of YAML-LD documents .
A YAML-LD document is any YAML document from which a conversion to [ JSON ] produces a valid JSON-LD document which can be interpreted as [ LINKED-DATA ].
The term media type is imported from [ RFC6838 ].
The term JSON is imported from [ JSON ].
The term JSON document represents a serialization of a resource conforming to the [ JSON ] grammar.
The terms JSON-LD document , and value object are imported from [ JSON-LD11 ].
The terms internal representation , and documentLoader are imported from [ JSON-LD11-API ].
The terms array , boolean , map , map entry , null , and string are imported from [ INFRA ].
The term number is imported from [ ECMASCRIPT ].
The terms YAML , YAML representation graph , YAML stream , YAML directive , TAG directive , YAML document , YAML sequence (either block sequence or flow sequence ), YAML mapping (either block mapping or flow mapping ), node , scalar , node anchor , node tags , and alias node , are imported from [ YAML ].
The term content negotiation is imported from [ RFC9110 ].
The terms RDF literal , language-tagged string , datatype IRI , and language tag are imported from [ RDF11-CONCEPTS ].
The terms fragment and fragment identifier in this document are to be interpreted as in [ URI ].
The term Linked Data is imported from [ LINKED-DATA ].
This section is non-normative.
This specification makes use of the following namespace prefixes:
| Prefix | IRI |
|---|---|
| ex | https://example.org/ |
| i18n | https://www.w3.org/ns/i18n# |
| rdf | http://www.w3.org/1999/02/22-rdf-syntax-ns# |
| rdfs | http://www.w3.org/2000/01/rdf-schema# |
| xsd | http://www.w3.org/2001/XMLSchema# |
| schema | https://schema.org/ |
| prov | http://www.w3.org/ns/prov# |
namespace-prefixes.yaml
.
These
are
used
within
this
document
as
part
of
a
compact
IRI
as
a
shorthand
for
the
resulting
IRI
,
such
as
schema:url
used
to
represent
https://schema.org/url
.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY , MUST , MUST NOT , RECOMMENDED , and SHOULD in this document are to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.
A YAML-LD document complies with the YAML-LD Basic profile of this specification if it follows the normative statements from this specification and can be transformed into a JSON-LD representation, then back to a conforming YAML-LD document, without loss of semantic information.
For convenience, normative statements for documents are often phrased as statements on the properties of the document.
This section is non-normative.
YAML is a superset of JSON, i.e., every valid JSON document is also a valid YAML document. YAML also offers a number of extra features, chief amongst which is improved human readability due to the ability to use minimal punctuation.
YAML is more flexible than JSON, as illustrated by the comparison table below.
| Features | [ JSON ] | [ YAML ] |
|---|---|---|
| Allowed encodings | ||
| UTF-8 | ✅ | ✅ |
| UTF-16 | ❌ | ✅ |
| UTF-32 | ❌ | ✅ |
| Native data types | ||
{}
object
|
✅ | ✅ |
[]
array
|
✅ | ✅ |
| string | ✅ | ✅ |
| number | ✅ |
✅
integer floating point |
| bool | ✅ | ✅ |
| null | ✅ | ✅ |
| Features | ||
| Delimited strings, arrays, objects | ✅ | ✅ |
| Punctuation-free strings, arrays, objects | ❌ | ✅ |
| Custom types | ❌ | ✅ via tags |
| Cycles | ❌ | ✅ |
| Documents per file | 1 | ⩾ 1 via YAML stream |
| Comments | ❌ | ✅ |
| Anchors & aliases | ❌ | ✅ |
| Mapping key types |
string
|
Any type representable in YAML , from strings to mappings |
json-vs-yaml.yaml
.
The first goal of this specification is to allow a JSON-LD document to be processed and serialized into YAML, and then back into JSON-LD, without losing any semantic information.
This is always possible because
Example: The JSON-LD document below
{
"@context": "https://schema.org",
"@id": "https://w3.org/yaml-ld/",
"@type": "WebContent",
"name": "YAML-LD",
"author": {
"@id": "https://www.w3.org/community/json-ld",
"name": "JSON-LD Community Group"
}
}
Can
be
serialized
as
YAML
as
follows.
Note
that
entries
starting
with
@
need
to
be
enclosed
in
quotes
because
@
is
a
reserved
character
in
YAML.
"@context": https://schema.org
"@id": https://w3.org/yaml-ld/
"@type": WebContent
name: YAML-LD
author:
"@id": https://www.w3.org/community/json-ld
name:
JSON-LD
Community
Group
This
document
is
based
on
YAML
1.2.2,
but
YAML-LD
is
not
tied
to
a
specific
version
of
YAML.
Implementers
concerned
about
features
related
to
a
specific
YAML
version
can
specify
it
in
documents
using
the
%YAML
directive
(see
6.
Interoperability
Considerations
).
This section is non-normative.
string
Perspectives for support of the additional YAML features are analyzed in Extended Profile informative addendum to this specification.
A
YAML-LD
document
MUST
be
encoded
in
UTF-8,
to
ensure
interoperability
with
[
JSON
];
otherwise,
an
invalid-encoding
MUST
be
detected,
and
processing
aborted.
Since anchor names are a serialization detail, such anchors MUST NOT be used to convey relevant information, MAY be altered when processing the document, and MAY be dropped when interpreting the document as JSON-LD.
A YAML-LD document MAY contain anchored nodes and alias nodes , but its representation graph MUST NOT contain cycles; otherwise, a loading-document-failed error MUST be detected, and processing aborted.
When interpreting the document as JSON-LD, alias nodes MUST be resolved by value to their target nodes.
The
YAML-LD
document
in
the
following
example
contains
alias
nodes
for
the
{"@id":
"country:US"}
object:
"@context":
"@import": https://schema.org
country: https://example.org/country/
"@included":
- &US
"@id": country:US
- "@id": https://www.w3.org/community/json-ld
"@type": Organization
member:
- "@id": https://github.com/gkellogg
"@type": Person
name: Gregg Kellogg
country: *US
- "@id": https://github.com/BigBlueHat
"@type": Person
name: Benjamin Young
country: *US
#
-
…
While the representation graph (and eventually the in-memory representation of the data structure, e.g., a Python dictionary or a Java hashmap) will still contain references between nodes, the JSON-LD serialization will not — since, by the time it is formed, all the anchors have been resolved, as shown below.
{
"@context": {
"@import": "https://schema.org",
"country": "https://example.org/country/"
},
"@included": [
{
"@id": "country:US"
},
{
"@id": "https://www.w3.org/community/json-ld",
"@type": "Organization",
"member": [
{
"@id": "https://github.com/gkellogg",
"@type": "Person",
"name": "Gregg Kellogg",
"country": {
"@id": "country:US"
}
},
{
"@id": "https://github.com/BigBlueHat",
"@type": "Person",
"name": "Benjamin Young",
"country": {
"@id": "country:US"
}
},
…
]
}
]
}
Mapping
key
type
MUST
be
a
string
.
Otherwise,
a
processing
error
is
raised.
This section is non-normative.
See Security considerations in JSON-LD 1.1 . Also, see the YAML media type registration.
This section is non-normative.
For
general
interoperability
considerations
on
the
serialization
of
JSON
documents
in
[
YAML
],
see
YAML
and
the
Interoperability
consideration
of
application/yaml
[
I-D.ietf-httpapi-yaml-mediatypes
].
The YAML-LD format and the media type registration are not restricted to a specific version of YAML, but implementers that want to use YAML-LD with YAML versions other than 1.2.2 need to be aware that the considerations and analysis provided here, including interoperability and security considerations, are based on the YAML 1.2.2 specification.
This section has been submitted to the Internet Engineering Steering Group (IESG) for review, approval, and registration with IANA.
This section describes the information required to register the above media type according to [ RFC6838 ]
profile
A
non-empty
list
of
space-separated
URIs
identifying
specific
constraints
or
conventions
that
apply
to
a
YAML-LD
document
according
to
[
RFC6906
].
A
profile
does
not
change
the
semantics
of
the
resource
representation
when
processed
without
profile
knowledge,
so
that
clients
both
with
and
without
knowledge
of
a
profiled
resource
can
safely
use
the
same
representation.
The
profile
parameter
MAY
be
used
by
clients
to
express
their
preferences
in
the
content
negotiation
process.
If
the
profile
parameter
is
given,
a
server
SHOULD
return
a
document
that
honors
the
profiles
in
the
list
which
it
recognizes,
and
MUST
ignore
the
profiles
in
the
list
which
it
does
not
recognize.
It
is
RECOMMENDED
that
profile
URIs
are
dereferenceable
and
provide
useful
documentation
at
that
URI.
For
more
information
and
background
please
refer
to
[
RFC6906
].
This
specification
allows
the
use
of
the
profile
parameters
listed
in
and
additionally
defines
the
following:
http://www.w3.org/ns/json-ld#extended
When
used
as
a
media
type
parameter
[
RFC4288
]
in
an
HTTP
Accept
header
field
[
RFC9110
],
the
value
of
the
profile
parameter
MUST
be
enclosed
in
quotes
(
"
)
if
it
contains
special
characters
such
as
whitespace,
which
is
required
when
multiple
profile
URIs
are
combined.
When processing the "profile" media type parameter, it is important to note that its value contains one or more URIs and not IRIs. In some cases it might therefore be necessary to convert between IRIs and URIs as specified in section 3 Relationship between IRIs and URIs of [ RFC3987 ].
application/yaml
.yaml
.yamlld
This section is non-normative.
Here, we propose to YAML-LD users a bit of advice which, although optional, might suggest one or two useful thoughts.
…in order to achieve a greater level of reusability, performance, and human friendliness among YAML-LD aware systems. The [ json-ld-bp ] document is as relevant to YAML-LD as it is to [ JSON-LD11 ].
Instead, provide pre-built contexts that the user can reference by URL for a majority of common use cases.
YAML-LD is intended to simplify the authoring of Linked Data for a wide range of domain experts; its target audience is not comprised solely of IT professionals. [ YAML ] is chosen as a medium to minimize syntactic noise, and to keep the authored documents concise and clear. [ JSON-LD11 ] (and hence YAML-LD) Context comprises a special language of its own. A requirement to author such a context would make the domain expert's job much harder, which we, as system architects and developers, should try to avoid.
If most, or all, of a user's documents are based on one particular context, try to make it the default in order to rescue the user from copy-pasting the same technical incantation from one document to another.
For
instance,
according
to
[
JSON-LD11-API
],
the
expand()
method
of
a
JSON-LD
processor
accepts
an
expandContext
argument
which
can
be
used
to
provide
a
default
system
context.
If
possible,
map
JSON-LD
keywords
containing
the
@
character
to
keywords
that
do
not
contain
it.
The
@
character
is
reserved
in
YAML,
and
thus
requires
quoting
(or
escaping),
as
in
the
following
example:
"@context": https://schema.org
"@id": https://w3.org/yaml-ld/
"@type":
WebContent
The
need
to
quote
these
keywords
has
to
be
learnt,
and
introduces
one
more
little
irregularity
to
the
document
author's
life.
Further,
on
most
keyboard
layouts,
typing
quotes
will
require
Shift
,
which
reduces
typing
speed,
albeit
slightly.
In order to avoid this, the context might introduce custom mappings for JSON-LD keywords — to make authoring more convenient. The exact mapping might vary depending on the domain, but we provide two examples, both published at json-ld.org :
convenience.jsonld
maps
@id
→
id
and
so
on,
removing
the
@
character
dollar-convenience.jsonld
maps
@id
→
$id
and
so
on,
replacing
@
with
$
.
YAML-LD users may use a JSON-LD context provided as part of this specification, or a similar custom context, to improve the authoring experience and readability.
Unfortunately,
@context
keyword
cannot
be
aliased
as
per
JSON-LD
specification
and
will
have
to
stay
as-is.
Consider
Example
6
reformatted
using
the
$
-
convenience
context
:
"@context":
- https://json-ld.org/contexts/dollar-convenience.jsonld
- https://schema.org
$id: https://w3.org/yaml-ld/
$type:
WebContent
This section is non-normative.
Theoretically,
we
could
try
harvesting
YAML
comments
into
JSON-LD
documents.
We
would
define
a
specific
predicate,
like
https://json-ld.org/yaml-ld/comment
,
and
convert
every
#
My
comment
fragment
into
a
{"yaml-ld:comment":
"My
comment"}
piece
of
the
JSON-LD
document.
This would, however, have the following impacts on implementations:
This section is non-normative.
Every YAML-LD file is a YAML-LD stream and might contain multiple YAML-LD documents , as shown in the example below.
"@context": https://schema.org
"@id": https://w3.org/yaml-ld/
"@type": WebContent
name: YAML-LD
---
"@context": https://schema.org
"@id": https://www.w3.org/TR/json-ld11/
"@type": WebContent
name:
JSON-LD
YAML streams may correspond more directly to JavaScript Object Notation (JSON) Text Sequences , which are not presently part of the JSON-LD internal representation . The description here more closely aligns with how JSON-LD interprets HTML Scripts .
Current specification does not support this feature. Implementations MAY choose, for example, to do any of the following:
For interoperability considerations on YAML streams, see the relevant section in YAML Media Type .
This section is non-normative.
The YAML-LD specification relies upon YAML to serialize Linked Data to the extent that YAML is compatible with JSON, which simplifies the operation and usage of YAML-LD. However, the more expressive feature set of YAML invites us to represent Linked Data in a more expressive way.
In the cases described above, one of the possible expressive methods is a specific feature of YAML language. To leverage those methods, we propose an Extended YAML-LD Profile which will implement all such features.
When
converting
JSON-LD
to
RDF,
@type
translates
to
one
of
the
following:
rdf:type
edge
datatype
mark
for
a
Literal
node
Possible ways to specify this in YAML-LD are the following:
@context
,
but
there
we
can
only
say
that
the
node
is
an
IRI,
we
cannot
specify
a
particular
rdf:type
rdfs:domain
or
rdfs:range
properties
@type
keyword
Using a YAML Tag, as shown below:
%TAG !xsd! http://www.w3.org/2001/XMLSchema%23
---
"@context": https://schema.org
"@id": https://w3.org/yaml-ld/
dateModified:
!xsd:date
2023-06-26
Here,
%TAG
declares
the
!xsd:
prefix
for
tags
used
in
the
document.
YAML
treats
tags
as
IRIs,
which
brings
it
close
to
the
LD
family
of
data
formats.
Note
that
the
directives
section
must
be
separated
from
the
main
document
with
---
(a
line
containing
exactly
three
hyphens).
If a segment of a YAML document has to be repeated more than once, one of the following approaches can be taken:
@id
,
and
then
address
it
by
the
given
identifier
Use YAML anchors & aliases as shown in Example 4 .
Two alternative approaches have been proposed to implement the Extended profile:
This approach implies extending the JSON-LD internal representation to allow a more complete expression of native data types within YAML-LD, and allows use of the complete JSON-LD 1.1 Processing Algorithms and API [ JSON-LD11-API ] Application Programming Interface to manipulate extended YAML-LD documents.
A YAML-LD document complies with the YAML-LD extended profile of this specification if it follows the normative statements from this specification and can be transformed into the JSON-LD extended internal representation , then back to a conforming YAML-LD document, without loss of semantic information.
As [ YAML ] has well-defined representation requirements, all YAML-LD streams MUST form a well-formed stream and use alias node defined by a previous node with a corresponding anchor ; otherwise, a loading-document-failed error has been detected and processing is aborted.
The YAML-LD extended profile allows full use of anchor names and alias nodes subject to the requirements described above in this section.
If
the
extendedYAML
API
flag
is
true
,
the
processing
result
will
be
in
the
extended
internal
representation
.
When
processing
using
the
YAML-LD
Basic
profile
,
documents
MUST
NOT
contain
alias
nodes
;
otherwise,
a
profile-error
error
has
been
detected
and
processing
is
aborted.
YAML-LD processing is defined by converting YAML to the internal representation and using JSON-LD 1.1 Processing Algorithms and API to process on that representation, after which the representation is converted back to YAML. As information specific to a given YAML document structure is lost in this transformation, much of the specifics of that original representation are therefore lost in that conversion, limiting the ability to fully round-trip a YAML-LD document back to an equivalent representation. Consequently, round-tripping in this context is limited to preservation of the semantic representation of a document, rather than a specific syntactic representation.
The conversion process represented here is compatible with the description of "Composing the Representation Graph" from the 3.1.2 Load section of [ YAML ]. The steps described below for converting to the internal representation operate upon that YAML Ain’t Markup Language (YAML™) version 1.2.2 .
When operating using the YAML-LD Basic profile , it is intended that the common feature provided by most YAML libraries of transforming YAML directly to JSON satisfies the requirements for parsing a YAML-LD file.
As a developer, I want to be able to convert JSON-LD documents to YAML-LD by simply serializing the document using any standard YAML library, So that the resulting YAML is valid YAML-LD, resolving to the same graph as the original JSON-LD.
A YAML stream is composed of zero or more YAML documents .
Any error reported in a recursive processing step MUST result in the failure of this processing step.
From the YAML grammar , a YAML document MAY be preceded by a Document Prefix and/or a set of directives followed by a YAML bare document , which is composed of a single node .
Any error reported in a recursive processing step MUST result in the failure of this processing step.
Both block sequences and flow sequences are directly aligned with an array in the internal representation .
Any error reported in a recursive processing step MUST result in the failure of this processing step.
Both block mappings and flow mappings are directly aligned with a map in the internal representation .
mapping-key-error
error
has
been
detected
and
processing
MUST
be
aborted.
Any error reported in a recursive processing step MUST result in the failure of this processing step.
extendedYAML
flag
is
true
,
and
node
n
has
a
node
tag
t
,
n
is
mapped
as
follows:
tag:yaml.org.2002:
,
the
conversion
result
is
mapped
through
the
YAML
Core
Schema
.
https://www.w3.org/ns/i18n#
,
and
the
suffix
does
not
contain
an
underscore
(
"_"
),
the
conversion
result
is
a
language-tagged
string
with
value
taken
from
n
,
and
a
language
tag
taken
from
the
suffix
of
t
.
"_"
),
such
as
i18n:ar-eg_rtl
describe
a
combination
of
language
and
text
direction.
See
The
i18n
Namespace
in
[
JSON-LD11
].
Implementations may retain the representation as an YAML Integer , or YAML Floating Point , but a JSON-LD processor must treat them uniformly as a number , although the specific type of number value SHOULD be retained for round-tripping.
The conversion result is the value of the entry in the named nodes map having the node entry. If none exist, the document is invalid, and processing MUST end in failure.
If
an
alias
node
is
encountered
when
processing
the
YAML
representation
graph
and
the
extendedYAML
flag
is
false
,
the
YAML-LD
Basic
profile
has
been
selected.
A
profile-error
error
has
been
detected
and
processing
MUST
be
aborted.
If a cycle is detected, a processing error MUST be returned, and processing aborted.
The conversion process from the internal representation involves turning that representation back into a YAML representation graph and relies on the description of "Serializing the Representation Graph" from the 3.1.1 Dump section of [ YAML ] for the final serialization.
As the internal representation is rooted by either an array or a map , the process of transforming the internal representation to YAML begins by preparing an empty representation graph which will be rooted with either a YAML mapping or YAML sequence .
Although
outside
of
the
scope
of
this
specification,
processors
MAY
use
YAML
directives
,
including
TAG
directives
,
and
Document
markers
,
as
appropriate
for
best
results.
Specifically,
if
the
extendedYAML
API
flag
is
true
,
the
document
SHOULD
use
the
%YAML
directive
with
version
set
to
at
least
1.2
.
To
improve
readability
and
reduce
document
size,
the
document
MAY
use
a
%TAG
directive
appropriate
for
RDF
literals
contained
within
the
representation.
The
use
of
%TAG
directives
in
YAML-LD
is
similar
to
the
use
of
the
PREFIX
directive
in
[
Turtle
]
or
the
general
use
of
terms
as
prefixes
to
create
Compact
IRIs
in
[
JSON-LD11
]:
they
not
change
the
meaning
of
the
encoded
scalars.
%TAG !xsd! http://www.w3.org/2001/XMLSchema%23
---
"@context": https://schema.org
"@id": https://github.com/gkellogg
"@type": Person
name: !xsd!string Gregg Kellogg
birthDate:
!xsd!date
1970-01-01
Although
allowed
within
the
YAML
Grammar,
some
current
YAML
parsers
do
not
allow
the
use
of
"#"
within
a
tag
URI.
Substituting
the
"%23"
escape
is
a
workaround
for
this
problem,
that
will
hopefully
become
unnecessary
as
implementations
are
updated.
A concrete proposal in that direction would be to use a tag at the top-level of any "idiomatic" YAML-LD document, applying to the whole object/array that makes the document.
It might also include a version to identify the specification that it relates to, allowing for version announcement that could be used for future-proofing.
The following block is one example:
!yaml-ld
$context: http://schema.org
$type: Person
name
:
Pierre-Antoine
Champin
See Example 11 for an example of serializing the extended internal representation.
This algorithm describes the steps to convert each element from the internal representation into corresponding YAML nodes by recursively processing each element n .
xsd:string
,
the
conversion
is
a
YAML
scalar
with
the
value
taken
from
that
value
of
n
.
https://www.w3.org/ns/i18n#
.
true
or
false
based
on
the
value
of
n
.
null
.
This section identifies two application profiles for operating with YAML-LD:
Application profiles allow publishers to use YAML-LD either for maximum interoperability, or for maximum expressivity. The YAML-LD Basic profile provides for complete round-tripping between YAML-LD documents and JSON-LD documents. The YAML-LD extended profile allows for fuller use of YAML features to enhance the ability to represent a larger number of native datatypes and reduce document redundancy.
Application
profiles
can
be
set
using
the
JsonLdProcessor
API
interface,
as
well
as
an
HTTP
request
profile
(see
A.
IANA
Considerations
).
The YAML-LD Basic profile is based on the YAML Core Schema , which interprets only a limited set of node tags . YAML scalars with node tags outside of the defined range SHOULD be avoided and MUST be converted to the closest scalar type from the YAML Core Schema , if found. See E.3.1.5 Converting a YAML scalar for specifics.
Keys used in a YAML mapping MUST be strings .
Although YAML-LD documents MAY include node anchors , documents MUST NOT use alias nodes .
A YAML stream MUST include only a single YAML document , as the JSON-LD internal representation only supports a single document model.
The YAML-LD extended profile extends the YAML Core Schema , allowing node tags to specify RDF literals by using a JSON-LD extended internal representation capable of directly representing RDF literals .
As with the YAML-LD Basic profile , YAML-LD documents in the YAML-LD extended profile MUST NOT use encodings other than UTF-8.
As with the YAML-LD Basic profile , keys used in a YAML mapping MUST be strings .
YAML-LD docucments MAY use alias nodes , as long as dereferencing these aliases does not result in a loop.
As with the YAML-LD Basic profile , a YAML stream MUST include only a single YAML document , as the JSON-LD extended internal representation only supports a single document model.
Consier
something
like
!id
as
a
local
tag
to
denote
IRIs.
This specification defines the JSON-LD extended internal representation , an extension of the JSON-LD internal representation .
In addition to maps , arrays , and strings , the internal representation allows native representation of numbers , boolean values, and nulls . The extended internal representation allows for native representation of RDF literals , both with a datatype IRI , and language-tagged strings .
When transforming from the extended internal representation to the internal representation — for example when serializing to JSON or to the YAML-LD Basic profile — implementations MUST transform RDF literals to the closest native representation of the internal representation :
xsd:boolean
are
transformed
to
either
true
or
false
,
xsd:decimal
,
xsd:double
,
xsd:float
,
or
derived
datatypes,
are
transformed
to
a
native
number
,
An alternative would be to transform such literals to JSON-LD value objects , and we may want to provide a means of transforming between the internal representation and extended internal representation using value objects , but this treatment is consistent with [ YAML ] Core Schema Tag Resolution .
This specification extends the JSON-LD 1.1 Processing Algorithms and API [ JSON-LD11-API ] Application Programming Interface and the JSON-LD 1.1 Framing [ JSON-LD11-FRAMING ] Application Programming Interface to manage the serialization and deserialization of [ YAML ] and to enable an option for setting the YAML-LD extended profile .
The
JSON-LD
Processor
interface
is
the
high-level
programming
structure
that
developers
use
to
access
the
JSON-LD
transformation
methods.
The
updates
below
is
an
experimental
extension
of
the
JsonLdProcessor
interface
defined
in
the
JSON-LD
1.1
API
[
JSON-LD11-API
]
to
serialize
output
as
YAML
rather
than
JSON.
compact
()
compact
()
algorithm
to
serialize
the
the
result
as
YAML
rather
than
JSON
as
defined
in
E.3.2
Conversion
to
YAML
.
expand
()
expand
()
algorithm
to
serialize
the
the
result
as
YAML
rather
than
JSON
as
defined
in
E.3.2
Conversion
to
YAML
.
flatten
()
flatten
()
algorithm
to
serialize
the
the
result
as
YAML
rather
than
JSON
as
defined
in
E.3.2
Conversion
to
YAML
.
fromRdf
()
fromRdf
()
algorithm
to
serialize
the
the
result
as
YAML
rather
than
JSON
as
defined
in
E.3.2
Conversion
to
YAML
.
Otherwise, if both theuseNativeTypesandextendedYAMLflags are set and the datatype IRI of value is notxsd:string:
- If value is a language-tagged string set converted value to a new RDF literal composed of the lexical form of value and datatype IRI composed of
https://www.w3.org/ns/i18n#followed by the language tag of value .- Otherwise, et converted value to value .
toRdf
()
- Otherwise, if value is an RDF literal , value is left unmodified. This will only be the case when processing a value from an extended internal representation .
The
JsonLdOptions
type
is
used
to
pass
various
options
to
the
JsonLdProcessor
methods.
WebIDLpartial dictionary JsonLdOptions {
boolean extendedYAML = false;
};
In addition to those options defined in the JSON-LD 1.1 API [ JSON-LD11-API ] and JSON-LD 1.1 Framing [ JSON-LD11-FRAMING ], this specification defines these additional options:
extendedYAML
xsd:string
or
language-tagged
strings
as
scalar
values.
documentLoader
,
it
causes
documents
of
type
application/ld+yaml
to
be
parsed
into
a
YAML
representation
graph
and
generates
an
internal
representation
(or
extended
internal
representation
):
This
section
describes
an
update
to
the
built-in
LoadDocumentCallback
to
load
YAML
streams
and
documents
into
the
internal
representation
,
or
into
the
extended
internal
representation
if
the
extendedYAML
API
flag
is
true
.
The
LoadDocumentCallback
algorithm
in
[
JSON-LD11-API
]
is
updated
as
follows:
application/ld+yaml
,
followed
by
application/yaml
,
followed
by
the
other
specified
Content-Types
.
application/yaml
or
any
media
type
with
a
+yaml
suffix
as
defined
in
[
RFC6839
]
transform
document
to
the
internal
representation
(or
extended
internal
representation
)
as
described
in
E.3.1
Conversion
to
the
Internal
Representation
.
Additionally,
if
the
profile
parameter
includes
http://www.w3.org/ns/json-ld#extended
,
set
the
extendedYAML
option
to
true
.
These
updates
are
intended
to
be
compatible
with
other
updates
to
the
LoadDocumentCallback
,
such
as
Process
HTML
as
defined
in
[
JSON-LD11-API
].
The
YamlLdErrorCode
represents
the
collection
of
valid
YAML-LD
error
codes,
which
extends
the
JsonLdErrorCode
definitions.
WebIDLenum YamlLdErrorCode {
"invalid-encoding",
"mapping-key-error",
"profile-error"
};
invalid-encoding
mapping-key-error
profile-error
TODO: Implementations for Extended Internal Representation.
This approach is simpler than the Extended Internal Representation because it does not require any changes to the internal structures of existing JSON-LD libraries.
Instead, we implement two API functions:
extended_to_basic(extended_document:
YAML-LD)
→
YAML-LD
basic_to_extended(basic_document:
YAML-LD)
→
YAML-LD
rdflib
will
take
care
of
them
under
the
covers,
but
it
can
help
with
troubleshooting
and
optimization
to
know
what's
going
on.
So,
you
start
with
YAML,
convert
it
to
JSON,
perform
JSON-LD
Expansion,
convert
that
to
YAML-LD,
and
do
any
necessary
basic
→
extended
or
extended
→
basic
conversion
on
the
YAML-LD.
Alternatively,
your
library
might
do
YAML-LD
expansion
directly
on
the
initial
YAML
document,
and
then
do
any
necessary
basic
→
extended
or
extended
→
basic
conversion
on
the
YAML-LD.
Both of these functions recursively process the source document. Every branch and leaf are copied as is, unless they match one of the following cases.
Generally, these two equalities do not hold:
extended_to_basic(basic_to_extended(document))
=
document
basic_to_extended(extended_to_basic(document))
=
document
When
the
extended
→
basic
conversion
resolves
YAML
tags
we
no
longer
know
where
the
original
document
used
tags
and
where
it
used
@type
calls.
Thus,
information
is
lost.
Both of these functions lose information about anchors and references because they're resolved by the YAML processor underlying the implementation.
extended_to_basic
|
basic_to_extended
|
|
|---|---|---|
| YAML Tags |
Convert
YAML
!tags
→
@type
JSON-LD
keywords
|
(nothing) |
| Anchors and aliases | Resolve anchors and aliases | (nothing) |
| Comments | Keep as-is |
Remove
(Due to JSON-LD & Expansion.) |
Substitute
every
*alias
with
the
content
of
the
&anchor
alias
references
to.
This
is
standard
behavior
of
YAML
tools
and
libraries.
This section is non-normative.
Fragment
identifiers
used
with
application/ld+yaml
are
treated
as
in
RDF
syntaxes,
as
per
RDF
1.1
Concepts
and
Abstract
Syntax
[
RDF11-CONCEPTS
]
and
do
not
follow
the
process
defined
for
application/yaml
.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
4.3 Comments
Comments in YAML-LD documents are treated as white space.
See Interoperability considerations of [ I-D.ietf-httpapi-yaml-mediatypes ] for more details.