Skip to toolbar

Community & Business Groups

ODRL Version 2.1 JSON Encoding

Final Specification: 5 March 2015

This Version: http://www.w3.org/community/odrl/json/2.1/

Latest Version: http://www.w3.org/community/odrl/json/2/

Editors:
Jonas Öberg, Commons Machinery in Sweden AB jonasATcommonsmachinery.se
Stuart Myles, The Associated Press smylesATap.org
Lu Ai, The Associated Press laiATap.org

Status of this document

This work was published by the W3C ODRL 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.

The W3C ODRL Community Group publishes a Final Specification to indicate that the document is believed to be mature and stable for implementation by the wider community. This Final Specification is now endorsed by the W3C ODRL Community Group as appropriate for widespread deployment and that promotes the Community Groups’s mission.

Discussion and feedback of this document takes place on the W3C ODRL Community Group mailing list (see Contributor Archive). Feedback from the public is encouraged and can be send to public-odrl@w3.org (see Public Archive).


Copyright © 2015 the Contributors to the Final Specification, published by the W3C ODRL Community Group under the W3C Community Final Specification Agreement (FSA). A human-readable summary is available.

Table of contents


1. Overview

The ODRL Version 2.1 language is defined by the ODRL Model [ODRL-MODEL] and ODRL Common Vocabulary [ODRL-VOCAB] in an abstract manner to capture the semantics of the expression, without any specific syntax and/or encoding method.

This document describes how to encode both the Model and Common Vocabulary, including any community developed Profiles, using the JSON syntax [JSON] and using a JSON Schema [JSON-SCHEMA].

This document utlilizes the key words “MUST”, “MAY”, “REQUIRED”, and “OPTIONAL” in accordance to [RFC2119]. Lowercase wording is used in this document.

2. Approach

ODRL can express complex contracts and policies which may require quite sophisticated systems to evaluate contractual permissions, restrictions and duties. However, the ODRL in JSON encoding is designed to be lightweight and requires only standard JSON software to generate or parse the representation.

In order to make the JSON encoding of ODRL as “natural” as possible, certain terms which are represented in the ODRL Common Vocabulary as values become JSON properties. For example, both “assigner” and “assignee” are Role controlled vocabulary values of Party. However, in the JSON encoding, they are expressed as full-fledged Properties. This contrasts with the XML encoding which has a Party element and a Role attribute.

Similarly, the Asset object has a Relation controlled vocabulary with values of “target” and “output”. The JSON encoding directly represents these as first-class properties.

The ODRL Model and Common Vocabulary is designed in this manner, in part, to allow for extensibility. In other words, it is possible to add additional types of Party or other kinds of Asset. The JSON ODRL Encoding allows for this by using patternProperties – for example, for additional types of Party or Scope.

Unlike XML, JSON doesn’t support the concept of namespaces. This means that property values need to be expressed using globally unique identifiers, in order to be unambiguous. Therefore, one key implementation decision for ODRL in JSON is to require that terms drawn from the ODRL Common Vocabulary or any ODRL profile (such as RightsML [RIGHTSML]) must be expressed using complete URLs. (This differs from the XML encoding of ODRL, which allows various short forms of URLs to be used, like QNames [Q-NAMES] or QCodes [Q-CODES]).

All of the URIs used in ODRL JSON instances MUST follow those defined in the ODRL Ontology [ODRL-ONTO]. This includes URIs for policy types, actions, operators, operands, functions, scopes, conflict handling terms, and unsupported action-handling terms.

2.1 A Note on JSON-LD

JSON-LD [JSON-LD] (JSON for Linked Data) is a method to convey Linked Data using JSON. It is a W3C Recommendation and it is a JSON syntax for RDF (similar to the RDF/XML and Turtle syntaxes for RDF). If you would prefer to use JSON-LD, it is recommended that you use the ODRL Ontology [ODRL-ONTO] and appropriate software to parse and serialize the RDF triples using JSON-LD.

3. Examples

Example 1 Set

{
    "policytype": "http://www.w3.org/ns/odrl/2/Set",
    "policyid": "http://example.com/policy:0099",
    "permissions": [{
        "target": "http://example.com/asset:9898",
        "action": "http://www.w3.org/ns/odrl/2/reproduce"
    }],
    "prohibitions": [{
        "target": "http://example.com/asset:9898",
        "action": "http://www.w3.org/ns/odrl/2/modify"
    }]
}

Example 2 Offer

{
    "policytype": "http://www.w3.org/ns/odrl/2/Offer",
    "policyid": "http://example.com/policy:0231",
    "permissions": [
        {
            "target": "http://example.com/music:4545",
            "action": "http://www.w3.org/ns/odrl/2/play",
            "assigner": "http://example.com/sony:10",
            "duties": [{
                "action": "http://www.w3.org/ns/odrl/2/compensate",
                "constraints": [{
                    "name": "http://www.w3.org/ns/odrl/2/payAmount",
                    "operator": "http://www.w3.org/ns/odrl/2/eq",
                    "rightoperand": "0.50",
                    "rightoperanddatatype": "http://www.w3.org/2001/XMLSchema#decimal",
                    "rightoperandunit": "http://cvx.iptc.org/iso4217a/AUD"
                }]
            }]
        },
        {
            "target": "http://example.com/music:4545",
            "action": "http://www.w3.org/ns/odrl/2/copy",
            "constraints": [{
                "name": "http://www.w3.org/ns/odrl/2/count",
                "operator": "http://www.w3.org/ns/odrl/2/lteq",
                "rightoperand": "1"
            }],
            "assigner": "http://example.com/sony:10",
            "duties": [{
                "action": "http://www.w3.org/ns/odrl/2/compensate",
                "constraints": [{
                    "name": "http://www.w3.org/ns/odrl/2/payAmount",
                    "operator": "http://www.w3.org/ns/odrl/2/eq",
                    "rightoperand": "0.50",
                    "rightoperanddatatype": "http://www.w3.org/2001/XMLSchema#decimal",
                    "rightoperandunit": "http://cvx.iptc.org/iso4217a/AUD"
                }]
            }]
        }
    ]
}

Example 3 Agreement

{
    "policytype": "http://www.w3.org/ns/odrl/2/Agreement",
    "policyid": "http://example.com/policy:9001",
    "permissions": [
        {
            "target": "http://example.com/music:4545",
            "action": "http://www.w3.org/ns/odrl/2/play",
            "assigner": "http://example.com/sony:10",
            "assignee": "http://example.com/billie:888",
            "duties": [{
                "action": "http://www.w3.org/ns/odrl/2/compensate",
                "constraints": [{
                    "name": "http://www.w3.org/ns/odrl/2/payAmount",
                    "operator": "http://www.w3.org/ns/odrl/2/eq",
                    "rightoperand": "0.50",
                    "rightoperanddatatype": "http://www.w3.org/2001/XMLSchema#decimal",
                    "rightoperandunit": "http://cvx.iptc.org/iso4217a/AUD"
                }]
            }]
        },
        {
            "target": "http://example.com/music:4545",
            "action": "http://www.w3.org/ns/odrl/2/copy",
            "constraints": [{
                "name": "http://www.w3.org/ns/odrl/2/count",
                "operator": "http://www.w3.org/ns/odrl/2/lteq",
                "rightoperand": "1"
            }],
            "assigner": "http://example.com/sony:10",
            "assignee": "http://example.com/billie:888",
            "duties": [{
                "action": "http://www.w3.org/ns/odrl/2/compensate",
                "constraints": [{
                    "name": "http://www.w3.org/ns/odrl/2/payAmount",
                    "operator": "http://www.w3.org/ns/odrl/2/eq",
                    "rightoperand": "0.50",
                    "rightoperanddatatype": "http://www.w3.org/2001/XMLSchema#decimal",
                    "rightoperandunit": "http://cvx.iptc.org/iso4217a/AUD"
                }]
            }]
        }
    ]
}

Example 4 Request

{
    "policytype": "http://www.w3.org/ns/odrl/2/Request",
    "policyid": "http://example.com/policy:04311",
    "permissions":[ {
        "target": "http://example.com/news:0099",
        "action": "http://www.w3.org/ns/odrl/2/display",
        "assignee": "http://example.com/guest:0589"
    }]
}

Example 5 Ticket

{
    "policytype": "http://www.w3.org/ns/odrl/2/Ticket",
    "policyid": "http://example.com/policy:04311",
    "permissions": [{
        "target": "http://example.com/game:4589",
        "action": "http://www.w3.org/ns/odrl/2/play",
        "constraints": [{
            "name": "http://www.w3.org/ns/odrl/2/dateTime",
            "operator": "http://www.w3.org/ns/odrl/2/lteq",
            "rightoperand": "2010-12-31"
        }]
    }]
}

Example 6 Offer and Next Policy

{
    "policytype": "http://www.w3.org/ns/odrl/2/Offer",
    "policyid": "http://example.com/policy:5531",
    "permissions": [{
        "target": "http://example.com/wallpaper:2321",
        "action": "http://www.w3.org/ns/odrl/2/distribute",
        "constraints": [{
            "name": "http://www.w3.org/ns/odrl/2/spatial",
            "operator": "http://www.w3.org/ns/odrl/2/eq",
            "rightoperand": "http://www.itu.int/tML/tML-ISO-3166:it"
        }],
        "assigner": "http://example.com/sony:99",
        "duties": [
            {
                "action": "http://www.w3.org/ns/odrl/2/compensate",
                "constraints": [{
                    "name": "http://www.w3.org/ns/odrl/2/payAmount",
                    "operator": "http://www.w3.org/ns/odrl/2/eq",
                    "rightoperand": "1000.00",
                    "rightoperanddatatype": "http://www.w3.org/2001/XMLSchema#decimal",
                    "rightoperandunit": "http://cvx.iptc.org/iso4217a/EUR"
                }]
            },
            {
                "action": "http://www.w3.org/ns/odrl/2/nextPolicy",
                "target": "http://example.com/policy:7777"
            }
        ]
    }]
}

    {
        "policytype": "http://www.w3.org/ns/odrl/2/Set",
        "policyid": "http://example.com/policy:7777",
        "permissions": [{
            "target": "http://example.com/wallpaper:2321",
            "action": "http://www.w3.org/ns/odrl/2/display"
        }]
    }

Example 7 Privacy

{
    "policytype": "http://www.w3.org/ns/odrl/2/Privacy",
    "policyid": "http://example.com/policy:1111",
    "permissions": [{
        "target": "http://example.com/billie:888:personal-data",
        "action": "http://www.w3.org/ns/odrl/2/distribute",
        "constraints": [{
            "name": "http://www.w3.org/ns/odrl/2/purpose",
            "operator": "http://www.w3.org/ns/odrl/2/eq",
            "rightoperand": "http://www.w3.org/2002/01/P3Pv1:contact"
        }],
        "assigner": "http://example.com/billie:888",
        "assignee": "http://example.com/gov:health:au",
        "duties": [{
            "action": "http://www.w3.org/ns/odrl/2/delete",
            "target": "http://example.com/billie:888:personal-data",
            "constraints": [{
                "name": "http://www.w3.org/ns/odrl/2/dateTime",
                "operator": "http://www.w3.org/ns/odrl/2/eq",
                "rightoperand": "P30D"
            }]
        }]
    }]
}

Example 8 Permission and Prohibition

{
    "policytype": "http://www.w3.org/ns/odrl/2/Agreement",
    "policyid": "http://example.com/policy:3433",
    "conflict": "perm",
    "permissions": [{
        "target": "http://example.com/music:1234908",
        "action": "http://www.w3.org/ns/odrl/2/play",
        "assigner": "http://example.com/sony:10",
        "assignee": "http://example.com/billie:888"
    }],
    "prohibitions": [{
        "target": "http://example.com/music:1234908",
        "action": "http://oma.org/drm:ringtone",
        "assigner": "http://example.com/sony:10",
        "assignee": "http://example.com/billie:888"
    }]
}

Example 9 Inheritance

{
    "policytype": "http://www.w3.org/ns/odrl/2/Agreement",
    "policyid": "http://example.com/policy:5531",
    "inheritallowed": true,
    "permissions": [{
        "target": "http://example.com/report:2321",
        "action": "http://www.w3.org/ns/odrl/2/print",
        "assigner": "http://example.com/pub:88",
        "assignee": "http://example.com/billie:888"
    }]
}

{
    "policytype": "http://www.w3.org/ns/odrl/2/Agreement",
    "policyid": "http://example.com/policy:9999",
    "inheritfrom": "http://example.com/policy:5531",
    "permissions": [{
        "target": "http://example.com/report:2333",
        "action": "http://www.w3.org/ns/odrl/2/display",
        "assigner": "http://example.com/pub:88",
        "assignee": "http://example.com/class:IT01",
        "assignee_scope": "http://www.w3.org/ns/odrl/2/group"
    }]
}

Example 10 Social Network

{
   "policytype": "http://www.w3.org/ns/odrl/2/Agreement",
    "policyid": "http://example.com/policy:5109",
    "permissions": [{
        "target": "http://example.com/myPlace:billie:photos:football2010",
        "action": "http://www.w3.org/ns/odrl/2/display",
        "assigner": "http://example.com/myPlace:billie",
        "assignee": "http://example.com/myPlace:network:football",
        "assignee_scope": "http://www.w3.org/ns/odrl/2/group"
    }]
}

Example 11 Multiple Assets

{
    "policytype": "http://www.w3.org/ns/odrl/2/Set",
    "policyid": "http://example.com/policy:881212",
    "permissions":[ {
        "target": "http://example.com/archive2010",
        "x:collection": "http://example.com/x/database",
        "action": "http://www.w3.org/ns/odrl/2/index"
    }]
}

Example 12 A request to display (according to the Common Vocabulary) and distribute (according to RightsML)

{
    "policytype": "http://www.w3.org/ns/odrl/2/Request",
    "policyid": "http://example.com/policy:04311",
    "permissions": [
        {
            "target": "http://example.com/news:0099",
            "action": "http://iptc.org/std/RightsML/2011-10-07/distribute",
            "assignee": "http://example.com/guest:0589"
        },
        {
            "target": "http://example.com/news:0099",
            "action": "http://www.w3.org/ns/odrl/2/display",
            "assignee": "http://example.com/guest:0589"
        }
    ]
}

4. Schema

A schema for ODRL in JSON using JSON-schema v4 [JSON-SCHEMA].

   {
    "type": "object",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "ODRL JSON Schema",
    "description": "ODRL JSON Schema (Final 5 March 2015)",
    "id": "http://www.w3.org/ns/odrl/2/jsonschema#",
    "definitions": {"prohibdutytype": {
        "type": "array",
        "items": {
            "type": "object",
            "required": ["action"],
            "properties": {
                "assigner": {
                    "type": "string",
                    "format": "uri"
                },
                "assignee": {
                    "type": "string",
                    "format": "uri"
                },
                "assignee_scope": {
                    "type": "string",
                    "format": "uri"
                },
                "target": {
                    "type": "string",
                    "format": "uri"
                },
                "output": {
                    "type": "string",
                    "format": "uri"
                },
                "action": {
                    "type": "string",
                    "format": "uri"
                },
                "constraints": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "required": [
                            "name",
                            "operator",
                            "rightoperand"
                        ],
                        "properties": {
                            "name": {
                                "type": "string",
                                "format": "uri"
                            },
                            "operator": {
                                "type": "string",
                                "format": "uri"
                            },
                            "rightoperand": {"type": "string"},
                            "rightoperanddatatype": {"type": "string"},
                            "rightoperandunit": {"type": "string"},
                            "status": {"type": "string"}
                        }
                    }
                }
            },
            "patternProperties": {
                "^[a-z]+party": {
                    "type": "string",
                    "format": "uri"
                },
                "^[a-z]+_scope": {
                    "type": "string",
                    "format": "uri"                }
            }
        }
    }},
    "required": [
        "policyid",
        "policytype"
    ],
    "properties": {
        "policyid": {
            "type": "string",
            "format": "uri"
        },
        "policytype": {
            "type": "string",
            "format": "uri"
        },
        "conflict": {
            "type": "string",
            "enum": [
                "perm",
                "prohibit",
                "invalid"
            ]
        },
        "undefined": {
            "type": "string",
            "enum": [
                "support",
                "ignore",
                "invalid"
            ]
        },
        "inheritallowed": {"type": "boolean"},
        "inheritfrom": {
            "type": "string",
            "format": "uri"
        },
        "inheritrelation": {
            "type": "string",
            "format": "uri"
        },
        "policyprofile": {
            "type": "string",
            "format": "uri"
        },
        "permissions": {
            "type": "array",
            "items": {
                "type": "object",
                "required": ["action"],
                "properties": {
                    "assigner": {
                        "type": "string",
                        "format": "uri"
                    },
                    "assigner_scope": {
                        "type": "string",
                        "format": "uri"
                    },
                    "assignee": {
                        "type": "string",
                        "format": "uri"
                    },
                    "assignee_scope": {
                        "type": "string",
                        "format": "uri"
                    },
                    "target": {
                        "type": "string",
                        "format": "uri"
                    },
                    "output": {
                        "type": "string",
                        "format": "uri"
                    },
                    "action": {
                        "type": "string",
                        "format": "uri"
                    },
                    "constraints": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "required": [
                                "name",
                                "operator",
                                "rightoperand"
                            ],
                            "properties": {
                                "name": {
                                    "type": "string",
                                    "format": "uri"
                                },
                                "operator": {
                                    "type": "string",
                                    "format": "uri"
                                },
                                "rightoperand": {"type": "string"},
                                "rightoperanddatatype": {"type": "string"},
                                "rightoperandunit": {"type": "string"},
                                "status": {"type": "string"}
                            }
                        }
                    },
                    "duties": {"$ref": "#/definitions/prohibdutytype"}
                },
                "patternProperties": {
                    "^[a-z]+party": {
                        "type": "string"
                    },
                    "^[a-z]+_scope": {
                        "type": "string"
                    }
                }
            }
        },
        "prohibitions": {"$ref": "#/definitions/prohibdutytype"}
    }

}

5. Acknowledgements

The editors gratefully acknowledge feedback and contributions to this document from:

  • All members of the W3C ODRL Community Group

6. References

[ECMA-292] European Computer Manufacturers Association. ECMAScript
Language Specification 3rd Edition, December 1999. http://www.ecma-international.org/publications/files/ecma-st/ECMA-262.pdf
[JSON] D. Crockford. JavaScript Object Notation, RFC 4627. JSON.org. http://www.ietf.org/rfc/rfc4627.txt
[JSON-LD] Manu Sporny, Dave Longley, Gregg Kellogg, Markus Lanthaler, Niklas Lindström. JSON-LD 1.0 A JSON-based Serialization for Linked Data. W3C Recommendation 16 January 2014. http://www.w3.org/TR/json-ld/
[JSON-SCHEMA] K. Zyp – A JSON Media Type for Describing the Structure and Meaning of JSON Documents http://tools.ietf.org/html/draft-zyp-json-schema-04
[ODRL-MODEL] R. Iannella & S. Guth & D. Paehler & A. Kasten (eds). Open Digital Rights Language (ODRL) Version 2.1 – Core Model. Final Specification, W3C ODRL Community Group. http://www.w3.org/community/odrl/model/2.1/
[ODRL-VOCAB] R. Iannella, M. Steidl, S. Guth (eds). Open Digital Rights Language (ODRL) Version 2.1 – Common Vocabulary. Final Specification, W3C ODRL Community Group. http://www.w3.org/community/odrl/vocab/2.1/
[ODRL-XML] R. Iannella (eds). Open Digital Rights Language (ODRL) Version 2.1 – XML Encoding. Final Specification, W3C ODRL Community Group. http://www.w3.org/community/odrl/xml/2.1/
[ODRL-ONTO] M. McRoberts, V. Rodríguez Doncel. Open Digital Rights Language (ODRL) Version 2.1 – Ontology. Final Specification, W3C ODRL Community Group
http://www.w3.org/ns/odrl/2/
[QNAME] http://en.wikipedia.org/wiki/QName
[QCODE] NewsML Specification Version 2.4. International Press Telecommunications Council (IPTC) 2009 http://www.iptc.org/std/NewsML-G2/2.4/specification/NewsML-G2_2.4-spec-PCL.pdf
[RFC2119] Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. The Internet Society, March 1997. http://www.ietf.org/rfc/rfc2119.txt
[RIGHTSML] RightsML: The IPTC Standard for Machine Readable Rights. http://dev.iptc.org/RightsML
T. Bray & J. Paoli & C. M. Sperberg-McQueen & E. Maler & F. Yergeau (eds). Extensible Markup Language (XML) 1.0 (Fifth Edition). W3C Recommendation 26 November 2008. http://www.w3.org/TR/xml/
No Comments |