CBOR
is
a
compact
binary
data
serialization
and
messaging
format.
This
specification
defines
CBOR-LD
1.0,
a
CBOR-based
format
to
serialize
Linked
Data.
The
encoding
is
designed
to
leverage
the
existing
JSON-LD
ecosystem,
which
is
deployed
on
hundreds
of
millions
of
systems
today,
to
provide
a
compact
serialization
format
for
those
seeking
efficient
encoding
schemes
for
Linked
Data.
By
utilizing
semantic
compression
schemes,
compression
ratios
in
excess
of
60%
better
than
generalized
compression
schemes
are
possible.
This
format
is
primarily
intended
to
be
a
way
to
use
Linked
Data
in
storage
and
bandwidth
constrained
programming
environments,
to
build
interoperable
semantic
wire-level
protocols,
and
to
efficiently
store
Linked
Data
in
CBOR-based
storage
engines.
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://digitalbazaar.github.io/cbor-ld-spec/
for
the
Editor's
draft.
This
section
describes
the
status
of
this
document
at
the
time
of
its
publication.
Other
documents
may
supersede
this
document.
A
list
of
current
W3C
publications
and
the
latest
revision
of
this
technical
report
can
be
found
in
the
W3C
technical
reports
index
at
https://www.w3.org/TR/.
This
document
is
experimental.
There
is
a
reference
implementation
that
is
capable
of
demonstrating
the
features
described
in
this
document.
Publication
as
an
Editor's
Draft
does
not
imply
endorsement
by
the
W3C
Membership.
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
work
in
progress.
CBOR
is
a
compact
binary
data
serialization
and
messaging
format.
This
specification
defines
CBOR-LD
1.0,
a
CBOR-based
format
to
serialize
Linked
Data.
The
encoding
is
designed
to
leverage
the
existing
JSON-LD
ecosystem,
which
is
deployed
on
hundreds
of
millions
of
systems
today,
to
provide
a
compact
serialization
format
for
those
seeking
efficient
encoding
schemes
for
Linked
Data.
By
utilizing
semantic
compression
schemes,
compression
ratios
in
excess
of
60%
better
than
generalized
compression
schemes
are
possible.
This
format
is
primarily
intended
to
be
a
way
to
use
Linked
Data
in
storage
and
bandwidth
constrained
programming
environments,
to
build
interoperable
semantic
wire-level
protocols,
and
to
efficiently
store
Linked
Data
in
CBOR-based
storage
engines.
1.1
How
to
Read
this
Document
This
section
is
non-normative.
This
document
is
a
detailed
specification
for
a
serialization
of
Linked
Data
in
CBOR.
The
document
is
primarily
intended
for
the
following
audiences:
Software
developers
who
want
to
encode
Linked
Data
in
a
variety
of
programming
languages
that
can
use
CBOR
Software
developers
who
want
to
convert
existing
JSON-LD
to
CBOR-LD
Software
developers
who
want
to
understand
the
design
decisions
and
language
syntax
for
CBOR-LD
Software
developers
who
want
to
implement
processors
and
APIs
for
CBOR-LD
Software
developers
who
want
to
generate
or
consume
Linked
Data,
an
RDF
graph,
or
an
RDF
Dataset
in
a
CBOR
syntax
1.1.1
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
word
MUST
in
this
document
is
to
be
interpreted
as
described
in
BCP
14
[
RFC2119
]
[
RFC8174
]
when,
and
only
when,
they
appear
in
all
capitals,
as
shown
here.
1.2
Contributing
This
section
is
non-normative.
There
are
a
number
of
ways
that
one
may
participate
in
the
development
of
this
specification:
The
working
group
uses
#json-ld
IRC
channel
is
available
for
real-time
discussion
on
irc.w3.org
.
The
#json-ld
IRC
channel
is
also
available
for
real-time
discussion
on
irc.freenode.net.
1.3
Design
Goals
and
Rationale
This
section
is
non-normative.
CBOR-LD
satisfies
the
following
design
goals:
Simplicity
Implementations
should
be
simple
to
implement
given
an
existing
JSON-LD
implementation.
Efficient
Storage
The
encoding
process
should
generate
an
aggressively
compact
Linked
Data
binary
format.
Generalized
Algorithm
The
encoding
algorithm
must
be
generalized.
Semantic
Compression
The
encoding
format
should
maximize
compression
of
Linked
Data
URLs
(terms
and
values).
Focusing
here
ensures
that
the
algorithms
can
achieve
compression
ratios
better
than
generalized
compression
algorithms.
Raw
Binary
Base-encoded
binary
values,
and
other
compressible
data
types,
should
be
translated
to
their
raw
binary
forms
from
base-encoded
formats
when
possible
without
sacrificing
generality.
Similarly,
the
following
are
non-goals.
Theoretical
purity.
Creating
new
compaction/expansion
algorithms
specifically
for
CBOR-LD.
Large
centralized
registries
for
every
term
on
the
planet.
Data
formats
that
require
large
spec
changes
or
complex
implementations
to
roundtrip
from
JSON-LD
to
CBOR-LD
and
back.
The
following
minefields
have
been
identified
while
working
on
this
specification:
While
it
is
widely
believed
that
hashing
is
fast,
it's
slower
than
string
comparison
over
a
small
set
of
strings.
This
is
true
because
in
order
to
hash,
you
must
consume
the
entire
string.
If
you
are
performing
string
comparisons,
you
can
abort
the
second
the
byte-for-byte
comparison
fails.
That
is,
when
processing
two
values,
string
comparison
can
abort
processing
and
hashing
cannot.
While
most
globally
collision-resistant
hashes
are
256-bits,
32
byte
values
are
large
and
we
can
do
better
in
many
cases
without
sacrificing
collision
resistance
(which
hashing
algorithms
like
blake2b-8
cannot
do).
Anything
that
requires
you
to
pre-process
the
JSON-LD
data
is
a
non-starter
--
it's
expensive,
and
that
means
that
you
are
encoding
semantics
in
the
data.
While
this
can
lead
to
better
compression
in
some
cases,
it
increases
the
complexity
of
the
processors
without
providing
an
acceptable
return
on
investment.
Scoped
contexts
are
the
most
challenging
aspect
of
a
more
generalized
solution.
The
deeper
the
algorithm
has
to
understand
scoping,
the
more
combinatorial
the
problem
becomes
and
thus
the
more
possible
compression
values
there
are,
which
harms
compression
size.
The
trick
is
to
leverage
the
determinism
in
the
existing
JSON-LD
Processing
algorithms
and
take
shortcuts
only
when
it
won't
affect
JSON-LD
processing.
2.
Basic
Concept
This
section
is
non-normative.
The
general
CBOR-LD
encoding
algorithm
takes
a
JSON-LD
Document
and
does
the
following:
Determine
if
JSON-LD
can
be
compressed
(@context
values
in
JSON-LD
document
that
reference
contexts
via
URLs
-
embedded
context
values
cannot
be
compressed)
Process
a
JSON-LD
Context,
building
a
CBOR-LD
term
codec
map
--
a
list
of
all
terms
that
can
be
compressed
(and
whether
or
not
their
values
can
be
compressed).
Sort
the
list.
Associate
byte
values
with
each
term
starting
at
0
and
counting
up.
Encoding
the
JSON-LD
Document
as
CBOR-LD
consists
of
replacing
every
key
with
the
byte
value
associated
with
the
term.
For
every
value
that
is
"@type":
"@id"
,
replace
the
value
with
the
byte
value
associated
with
the
term.
Decoding
the
CBOR-LD
Bytes
as
JSON-LD
consists
of
replacing
every
CBOR
key
with
the
associated
value
in
the
term
codec
map.
For
every
value
that
is
"@type":
"@id"
,
replace
the
value
with
the
byte
value
associated
with
the
term.
3.
Algorithms
3.1
JSON-LD
to
CBOR-LD
Algorithm
This
algorithm
takes
a
JSON-LD
object
jsonldDocument
and
options
as
input.
Let
result
be
an
empty
CBOR-encoded
byte
array.
Initialize
contextUrls
to
the
return
value
of
the
"Get
Context
URLs
Algorithm"
passing
jsonldDocument
as
input.
If
the
"Get
Context
URLs
Algorithm"
resulted
in
an
error,
set
result
to
the
return
value
of
the
"Generate
Uncompressed
CBOR-LD
Algorithm".
Otherwise,
set
result
to
the
return
value
of
the
"Generate
Compressed
CBOR-LD
Algorithm"
passing
contextUrls
as
options.contextUrls
.
Return
result
.
3.2
Uncompressed
CBOR-LD
Buffer
Algorithm
This
algorithm
takes
a
JSON-LD
object
jsonldDocument
and
options
as
input.
Let
result
be
an
empty
CBOR-encoded
byte
array.
Set
the
first
two
bytes
(CBOR
Tag)
to
0x0500
(CBOR-LD
-
0x05,
Uncompressed
-
0x00,
Tag
1280))
For
every
key-value
in
the
map,
generate
the
Uncompressed
CBOR-LD
Buffer
by
converting
it
to
the
associated
CBOR-LD
header
and
value.
For
complex
values
(maps,
arrays),
recursively
convert
the
value
to
something
that
will
losslessly
encode
and
decode
back
to
JSON-LD.
Return
the
Uncompressed
CBOR-LD
Buffer.
3.3
Compressed
CBOR-LD
Buffer
Algorithm
This
algorithm
takes
a
JSON-LD
object
jsonldDocument
and
options
as
input.
The
options
MUST
contain:
applicationContextMap
A
map
of
application-specific
JSON-LD
context
URL
strings
that
are
mapped
to
their
encoded
CBOR-LD
values.
The
values
MUST
be
values
greater
than
32767
(0x7FFF).
Values
from
0-32767
(0x0-0x7FFF)
are
reserved
for
globally
recognized
JSON-LD
Context
URL
values.
applicationTermMap
A
map
of
JSON-LD
terms
and
their
associated
CBOR-LD
term
codecs.
Let
result
be
an
empty
CBOR-encoded
byte
array.
Set
the
first
three
bytes
of
result
to
0xd90501
(CBOR
Tag
-
0xd9,
CBOR-LD
-
0x05,
Compressed
-
CBOR-LD
compression
algorithm
version
1
-
0x01,
Tag
1281)).
Add
to
result
by
recursively
processing
every
name-value
pair
in
jsonldDocument
Let
termHint
be
the
value
associated
with
the
JSON
name
in
the
termCodecMap
.
Set
the
CBOR
key
to
the
termHint.value
value.
Set
the
CBOR
value
to
the
result
of
the
termHint.valueCompressor
function.
Return
result
.
3.4
Get
Term
Codec
Map
Algorithm
This
algorithm
takes
a
list
of
URL
strings
contextUrls
and
returns
a
CBOR-LD
term
codec
map
that
maps
JSON-LD
terms
to
their
associated
byte
values
and
value
compression
functions.
Let
result
be
an
ordered
map.
For
each
value
in
contextUrls
,
dereference
the
JSON-LD
contexts
and
process
every
entry.
Set
the
entry
key
to
the
JSON-LD
term
key.
Set
the
entry
value
to
an
unordered
map
with
two
entries.
The
first
entry
should
be
set
to
value
with
an
undefined
value.
Let
compressor
be
a
known
global
compressor
function
associated
with
the
@type
property,
a
known
local
compressor
function
that
was
provided
to
this
function,
or
the
generic
CBOR
compressor
function,
which
returns
the
bytes
associated
with
a
typical
CBOR
compression
of
the
given
datatype.
Let
sortedTerms
be
the
value
of
sorting
all
of
the
keys
in
result
.
For
every
value
in
the
list
of
sortedTerms
set
the
associated
termHint.value
value
to
the
associated
index
of
sortedTerms
.
Return
result
.
3.5
Get
Context
URLs
Algorithm
Let
result
be
a
ordered
map.
Walk
the
JSON
tree,
for
each
JSON
name-value
pair:
If
the
name
is
@context
Add
all
values
that
are
referenced
by
a
URL
to
result
where
the
key
in
the
map
is
set
to
the
JSON
value
associated
with
@id
.
If
a
non-URL
value
is
detected,
throw
an
ERR_NON_URL_JSONLD_CONTEXT_DETECTED
error.
Return
result
.
A.
Term
Codec
Registry
The
following
is
a
registry
of
well-known
term
codecs.
These
will
be
registered
on
a
first-come
first-serve
basis.