[
JSON-LD11
]
is
a
JSON-based
format
to
serialize
Linked
Data
[
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
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
[
RFC9512
]),
this
document
identifies
constraints
on
YAML
such
that
any
YAML-LD
document
can
be
represented
in
JSON-LD.
Status
of
This
Document
This
is
a
preview
Do
not
attempt
to
implement
this
version
of
the
specification.
Do
not
reference
this
version
as
authoritative
in
any
way.
Instead,
see
https://w3c.github.io/yaml-ld/
for
the
Editor's
draft.
This
section
describes
the
status
of
this
document
at
the
time
of
its
publication.
A
list
of
current
W3C
publications
and
the
latest
revision
of
this
technical
report
can
be
found
in
the
W3C
standards
and
drafts
index
.
Publication
as
an
Editor's
Draft
does
not
imply
endorsement
by
W3C
and
its
Members.
This
is
a
draft
document
and
may
be
updated,
replaced,
or
obsoleted
by
other
documents
at
any
time.
It
is
inappropriate
to
cite
this
document
as
other
than
a
work
in
progress.
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.
This
document
is
intended
primarily
for
two
main
audiences,
as
described
below.
Software
developers
who
want
to
—
encode
Linked
Data
in
a
variety
of
programming
languages
which
can
use
YAML
convert
existing
YAML
to
YAML-LD
understand
the
design
decisions
and
language
syntax
for
YAML-LD
implement
processors
and
APIs
for
YAML-LD
generate
or
consume
Linked
Data,
an
RDF
Graph,
or
an
RDF
Dataset
in
a
YAML
syntax
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
—
consumed
by
programming
systems
capable
of
understanding
YAML-LD
transformed
with
JSON-LD
framing
algorithms
published
on
the
Web
for
human
and
machine
consumption
For
these
users,
familiarity
with
JSON-LD
is
not
required,
but
understanding
of
Linked
Data
principles
might
be
beneficial.
1.2
Terminology
This
section
is
non-normative.
This
document
uses
the
following
terms
as
defined
in
external
specifications
and
defines
terms
specific
to
JSON-LD.
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
.
2.
Conformance
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-LD11
]
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.
Since
YAML
is
a
superset
of
JSON
,
testing
a
YAML-LD
implementation
against
test
cases
from
JSON-LD
test
suites
should
be
trivial.
3.
Basic
Concepts
This
section
is
non-normative.
3.1
JSON
vs
YAML
comparison
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.
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.
{"@context":"https://schema.org","@id":"https://w3c.github.io/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://w3c.github.io/yaml-ld/"@type":WebContentname:YAML-LDauthor:"@id":https://www.w3.org/community/json-ld
name:
JSON-LD
Community
Group
This
specification
is
based
on
YAML
1.2.2.
YAML-LD
processors
MUST
use
a
YAML
1.2
(or
later,
backward-compatible)
implementation.
Implementers
may
specify
the
YAML
version
in
documents
using
the
%YAML
directive
(see
8.
Interoperability
Considerations
).
See
8.
Interoperability
Considerations
for
interoperability
concerns
with
YAML
1.1.
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
during
YAML-LD
processing.
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.
Example
5
:
JSON-LD
resulting
from
YAML
with
node
anchors
Mapping
key
type
MUST
be
a
string
.
Otherwise,
a
processing
error
is
raised.
4.6
Scalar
Value
Types
YAML-LD
uses
the
YAML
Core
Schema
for
scalar
type
resolution.
Float
values
that
cannot
be
represented
in
[
JSON
]
—
specifically
infinity
(
.inf
,
-.inf
,
+.inf
)
and
not-a-number
(
.nan
)
—
MUST
cause
a
loading-document-failed
error.
The
YAML
Core
Schema
does
not
define
a
timestamp
type;
scalars
such
as
2018-04-01
resolve
to
plain
strings.
However,
many
YAML
libraries
implement
YAML
1.1
timestamp
resolution
by
default
and
will
silently
convert
such
scalars
to
native
date
or
datetime
objects.
YAML-LD
processors
MUST
NOT
perform
such
conversion
and
MUST
treat
these
values
as
strings.
Note
:
Core
Schema
type
resolution
4.7
JSON
literals
This
section
is
non-normative.
The
@json
keyword
from
JSON-LD
1.1
defines
a
JSON
literal
as
a
value
object
with
@type
@json
and
@value
containing
JSON
data.
A
processor
treats
such
a
value
as
a
JSON
literal,
rather
than
interpreting
it
further
as
JSON-LD.
Consider
the
following
example.
Example
6
:
JSON
literal
metadata
about
YAML-LD
specification
Although
the
keyword
is
named
@json
,
it
does
not
require
the
value
of
@value
to
be
written
using
JSON
syntax
in
YAML-LD.
As
this
example
shows,
the
metadata
value
object
is
preserved
during
expansion
in
its
JSON-LD
form,
—
as
this
keyword
mandates.
For
general
interoperability
considerations
on
the
serialization
of
JSON
documents
in
[
YAML
],
see
YAML
and
the
Interoperability
considerations
of
the
+yaml
structured
syntax
suffix.
The
considerations
and
analysis
provided
here,
including
interoperability
and
security
considerations,
are
based
on
the
YAML
1.2.2
specification.
Many
popular
YAML
libraries
default
to
YAML
1.1
parsing.
YAML
1.1
implementations
cause
interoperability
issues;
in
particular,
the
so-called
"Norway
problem"
arises
because
YAML
1.1
treats
no
,
No
,
NO
,
yes
,
on
,
off
,
and
similar
values
as
booleans,
whereas
YAML
1.2
Core
Schema
treats
them
as
plain
strings.
YAML-LD
processors
that
use
a
YAML
1.1
library
will
fail
the
conformance
tests
and
are
not
compliant.
9.
Embedding
YAML-LD
in
HTML
Documents
YAML-LD
content
can
be
easily
embedded
in
HTML
[
HTML
]
by
placing
it
in
a
<script>
element
with
the
type
attribute
set
to
application/ld+yaml
,
as
illustrated
in
an
example
below.
YAML
syntax
is
indentation
based.
Therefore,
when
processing
each
<script>
block
with
YAML-LD
content,
YAML-LD
processor
MUST
preserve
the
content
of
the
block
for
YAML
parsing
as-is
,
including
whitespace
characters.
If
the
YAML-LD
<script>
tag
contains
a
YAML
Stream
with
multiple
YAML
documents
,
each
of
these
documents
MUST
be
treated
as
if
it
was
included
in
a
separate
<script>
tag.
See
Streams
for
details.
A
conformant
YAML-LD
specification
MUST
take
this
flag
into
account
while
parsing
a
normal
YAML-LD
document.
If
the
flag
is
true
,
the
YAML
stream
is
considered
an
array,
and
each
document
in
it
is
an
item
in
that
array,
even
if
there
is
only
one
document
in
the
stream;
If
the
flag
is
false
,
only
the
first
document
in
the
stream
will
be
processed.
Note
:
Interoperability
considerations
on
YAML
streams
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
]
A.1
application/ld+yaml
Type
name:
application
Subtype
name:
ld+yaml
Required
parameters:
N/A
Optional
parameters:
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
is
a
placeholder
for
specifying
something
like
an
extended
YAML-LD
document
form
making
use
of
YAML-specific
features.
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
].
must
not
be
used
to
convey
application
level
information.
B.2
Predictability
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:
They
would
be
more
complicated,
because
most
industrially
available
YAML
parsers
discard
comments
on
reading
YAML
data
They
would
be
less
predictable,
because
order
of
keys
is
not
preserved
in
JSON
—
and
therefore,
when
converting
a
JSON-LD
document
back
to
YAML-LD,
comments
might
be
displaced.
C.
Acknowledgements
This
section
is
non-normative.
C.1
In
Memoriam
Gregg
Kellogg
was
a
central
figure
in
the
story
of
JSON-LD
and
YAML-LD.
He
worked
tirelessly
on
JSON-LD
and
many
other
specifications
for
more
than
a
decade,
right
up
until
his
death
on
September
6th,
2025.
Gregg's
passion
for
solving
hard
problems
with
finesse
was
only
exceeded
by
his
willingness
to
collaborate
with
and
encourage
others
in
reaching
that
destination.
The
JSON-LD
and
broader
Linked
Data
communities
will
be
forever
grateful
for
Gregg's
consistent,
careful,
and
kindly
delivered
contributions
during
their
most
formative
years.
C.2
Contributions
The
editors
would
especially
like
to
thank
the
following
individuals
for
making
significant
contributions
to
the
authoring
and
editing
of
this
specification:
4.3 Comments
Comments in YAML-LD documents are treated as white space.
See Interoperability considerations of "+yaml" structured syntax suffix for more details.