[[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.

This specification was initially developed by the JSON-LD Community Group.

Introduction

YAML-LD applies JSON-LD's data model and processing model to YAML so that Linked Data can be written in a YAML syntax while remaining representable as JSON-LD.

It is intended for documents that are read and written by humans and by software agents, including those based on Large Language Models.

An introductory YAML-LD example is presented below. 


        

          

        

      


  

    
How to read this document


    

      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.
    


    
  


  

    
Terminology


    
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.
      On disk or on the wire, YAML-LD is always exchanged as a YAML-LD stream
      (one stream per file or HTTP body), containing one or more 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]].
    

  


  

    
Namespace Prefixes


    
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#
        

      
    


    

      See YAML-LD version of this table at
      
        namespace-prefixes.yamlld
      .
    


    
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.
    

  

  




  

    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.
  


  

    
Base Specification Versions


    
YAML-LD supports [[[JSON-LD11]]] [[JSON-LD11]] and later.


    

      YAML-LD is based on [[[YAML]]] [[YAML]].
      YAML-LD processors MUST use a YAML 1.2 (or later, backward-compatible)
      implementation; see  for the
      interoperability concerns that arise with YAML 1.1.
      Implementers MAY specify the YAML version in a given document
      by using the `%YAML` directive.
    

  


  

    
Test Suites


    
To be conformant, an implementation MUST satisfy all test cases from the following test suites:


    

    
...disregarding the test cases where:


    

    

      Since YAML is a superset of JSON, testing a YAML-LD implementation against
      test cases from JSON-LD test suites should be trivial.
    

  




  

    
Basic Concepts


    

      
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 among which is improved
        human readability due to the minimized punctuation requirements.

      
YAML is more flexible than JSON, as illustrated by the comparison table below.


      

        
        

          Features
          [[JSON]]
          [[YAML]]
          YAML-LD
        

        
        
        

          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
          Core Schema only
        


        

          Documents per file
          1
          ⩾ 1 via YAML stream
          ⩾ 1 (depending on extractAllScripts flag, see Stream Processing)
        


        

          Comments
          ❌
          ✅
          ✅ Treated as Whitespace
        


        

          Anchors & aliases
          ❌
          ✅
          ✅ Anchor names do not bear semantic information
        


        

          Cycles
          ❌
          ✅
          ❌ Not permitted
        


        

          Mapping key types
          string
          
            Any type representable in YAML, from strings to mappings
          
          string
        

        
      


      

        See YAML-LD version of this table at
        
          json-vs-yaml.yamlld
        .
    

    


      

        [[?eriksson-hallberg]] showed that, although YAML can be larger than equivalent JSON for some deeply nested documents,
        for many flatter documents it is smaller than pretty-printed JSON while remaining human-readable.
        That combination can reduce the amount of text that large language models and other software agents
        must process, without requiring a separate minified encoding.

    

    
Goal of this specification

    

The 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


    

    
JSON-LD serialization of Example 1:

    

  

  


  

    
Core Requirements


    

      [[[YAML]]] describes YAML processing in a number of steps, reproduced in .
      This processing transforms a stream of characters in the YAML syntax (on the right) to and from a so-called "native data structure" (on the left).
      In JSON-LD, that data structure is the JSON-LD [=internal representation=].
    

    

      YAML Processing Overview
      
YAML processing overview, from [[YAML]]

    


    

      This section describes the requirements imposed by YAML-LD on the YAML processing steps,
      in the load direction (right to left in ).
      Dump proceeds in the opposite direction, producing
      a conforming YAML-LD stream from a JSON-compatible [=internal representation=].
    


    

      
Presentation


      

        Presentation is the YAML character stream in .
      


      

        
Encoding


        

          

            JSON text exchanged between systems that are not part of a closed
            ecosystem MUST be encoded using UTF-8.
          

          
        


        

          A YAML-LD stream MUST be encoded in UTF-8;
          otherwise, an
          invalid-encoding
          error MUST be detected, and processing aborted.
        

      


      

        
Comments


        

          

            Comments are a presentation detail and must not have any effect on the
            serialization tree or representation graph.
          

          
        


        

          Comments in YAML-LD streams are treated as white space.
        


        

          See
          YAML and JSON interoperability considerations
          for more details.
        

      


      

        
Streams


        

          

            YAML allows several serialization trees to be contained in the same YAML
            presentation stream, as a series of documents separated by markers.
          

          
        


        

          A YAML-LD stream MAY contain more than one
          YAML-LD document, as shown below.
        


        

          

          

            

          

        


        

          For interoperability considerations on YAML streams,
          see the relevant section in YAML Media Type.
        

      

    


    

      
Serialization


      

        Serialization is the ordered tree produced by
        Parse
        (and consumed by
        Present)
        in .
      


      

        
Anchors and Aliases


        

          

            Anchor names are a serialization detail and are discarded once
            composing is completed.
          

          
        


        

          In this specification, anchor means YAML's
          node anchor mechanism
          (with alias nodes, using & and *
          in the serialization) to reuse the same logical node by reference in the serialized graph.
          It is not related to HTML hyperlinks
          or URL fragment identifiers.
          See [[YAML]]
          §6.9.2 Node Anchors.
        

        

          Consequently, anchor names
          MUST NOT be used to convey relevant information,
          MAY be altered when processing the document,
          and MAY be dropped during YAML-LD processing.
        


        

          Anchors are particularly useful within a @context block.
          When several terms share the same term definition — for example, all
          IRI-valued properties — the shared definition can be anchored once and
          aliased for each term, avoiding repetition.
          The following example anchors the IRI coercion definition as
          &iri and reuses it for three properties:
        


        

          

          

            

          

        


        

          Once all anchors and aliases have been resolved, the equivalent JSON-LD is:
        


        


        
      

    


    

      
Representation


      

        Representation is the YAML representation graph produced by
        Compose
        in .
      


      

        A YAML-LD document MAY contain anchored nodes and alias nodes
        in its serialization,
        but its representation graph MUST NOT contain cycles;
        otherwise, a
        loading-document-failed
        error MUST be detected, and processing aborted.
      


      

        When composing the representation graph, each alias node
        MUST resolve to the node identified by its target anchor.
        When constructing the JSON-LD [=internal representation=], each reference
        to that node MUST be treated as a copy of the node.
      


      

        
Scalar Value Types


        

          When composing a complete representation graph, 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 to be raised when constructing the JSON-LD [=internal representation=].
        

        

          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.
        


        

          YAML-LD does not assign additional JSON-LD meaning to node tags
          beyond the scalar type resolution defined by the
          YAML Core Schema.
        


        
      

    


    

      
Native Data Structure


      

        The native data structure produced by
        Construct in
        
        is the JSON-LD [=internal representation=].
      


      

        
Stream Processing


        

          [[JSON-LD11-API]] defines the
          `extractAllScripts` flag, which allows to parse
          multiple `<script>` tags with JSON-LD content in an HTML document.
        


        

          A conformant YAML-LD implementation MUST apply this flag when constructing
          the JSON-LD [=internal representation=] from a YAML-LD stream.
        


        
    
          
  • 
            If the flag is `true`, the internal representation MUST be an array
            containing the constructed value of each document in the stream,
            even if the stream contains only one document.
          
    • 
          
  • 
            If the flag is `false`, only the first document in the stream MUST be constructed.
          
    • 
        

      


      

        
Mapping Key Types


        

          

            An object structure is represented as a pair of curly brackets
            surrounding zero or more name/value pairs (or members).
            A name is a string.
          

          
        


        

          Consequently, all mapping keys in YAML-LD MUST be strings.
          Otherwise, a `mapping-key-error` error is raised.
        

      


      

        
JSON literals


        

          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.
        


        

          

          

            

          

        


        

          Consider the expanded form.
        


        


        

          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.
        


        

          When it is converted to RDF, the JSON literal's lexical form is
          JSON text reconstructed from the
          internal representation.
        

      

    

  


  

    
YamlLdErrorCode

    
The YamlLdErrorCode represents the collection of valid YAML-LD error codes,
      which extends the {{JsonLdErrorCode}} definitions.


    
enum YamlLdErrorCode {
  "invalid-encoding",
  "mapping-key-error",
  "profile-error"
};
    


    

      
invalid-encoding

      
The character encoding of an input is invalid.

      
mapping-key-error

      
A YAML mapping key was found that was not a string.

      
profile-error

      
The parsed YAML document contains features incompatible with the specified profile.

    

  


  

    
Security Considerations


    
See Security considerations in JSON-LD 1.1
       and +yaml structured syntax suffix.

  


  

    
Privacy Considerations


    
See Privacy considerations in JSON-LD 1.1.
  


  

    
Interoperability Considerations


    

      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.
    

  


  

    
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 Stream Processing for details.
    

  


  

    
IANA Considerations


    
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]]
    


    

    
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 stream 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

              
To request or specify the YAML-LD Extended Profile.
                

                  This is a placeholder for specifying something like the
                  YAML-LD Extended Profile
                  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]].

          

        

      

      
Encoding considerations:

      
Same as +yaml.

      
Security considerations:

      
See .

      
Interoperability considerations:

      
See .

      
Published specification:

      
http://www.w3.org/TR/yaml-ld

      
Applications that use this media type:

      
Any programming environment that requires the exchange of
        directed graphs.
      

      
Additional information:

      

        

          
Deprecated alias names for this type:

          
N/A

          
Magic number(s):

          
Same as application/yaml

          
File extension(s):

          

            
    
              
  • .yaml
    • 
              
  • .yamlld
    • 
            

          

          
Macintosh file type code(s):

          
Same as application/yaml

          
Windows Clipboard Name:

          
Same as application/yaml

        

      

      
Person & email address to contact for further information:

      
W3C JSON-LD Working Group <public-json-ld-wg@w3.org>

      
Intended usage:

      
Common

      
Restrictions on usage:

      
N/A

      
Author(s):

      
Roberto Polli, Gregg Kellogg

      
Change controller:

      
W3C

    

    

  


  

    
Why are comments treated as whitespace?


    

      
Consistency


      

        
[[?TURTLE]] and other Linked Data serializations which support comments

        
do not provide a means to preserve them
          when processing and serializing the document
          in other formats
        


        
YAML

        

          requires that parts of the document not reflected by

          representation graph, such as

          
    
            
  • comments
    • 
            
  • directives
    • 
            
  • mapping key order
    • 
            
  • anchor names
    • 
          


          must not be used to convey application level information.
        

      

    


    

      
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:
      


      
    

  

    

      
Acknowledgements


      
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.


      
Contributions

      

          The editors would especially like to thank the following individuals for making significant
          contributions to the authoring and editing of this specification: