ODRL Version 2.1 JSON Encoding

Working document for JSON Encoding of ODRL

Draft Specification: 13 October 2014

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 Draft Specification is not yet 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 © 2014 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
  2. Approach
  3. Examples
  4. Acknowledgements
  5. References

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 utlilises the key words “MUST”, “MAY”, “REQUIRED”, and “OPTIONAL” in accordance to [RFC2119]. Lowercase wording is used in this document.

Approach

The ODRL in JSON encoding is designed to be light weight. In particular, it only requires standard JSON software to generate or parse the representation. Of course, evaluating the permissions, restrictions and duties encoded in JSON may require quite sophisticated systems, in some situations.

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 have been made JSON properties. For example, “assigner” and “assignee” are both values in the Role controlled vocabulary of Party. However, in the JSON encoding, they are 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 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 way, 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]).

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

JSON-schema

A draft schema using JSON-schema v4 [JSON-SCHEMA].

   {
    "type": "object",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "ODRL JSON Schema",
    "description": "ODRL JSON Schema (Draft September 2014)",
    "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"}
    }
 
}

Acknowledgements

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

  • All members of the W3C ODRL Community Group

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-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.0 – Core Model. Final Specification, W3C ODRL Community Group. http://www.w3.org/community/odrl/two/model/

[ODRL-VOCAB]

S. Guth & R. Iannella (eds). Open Digital Rights Language (ODRL) Version 2.0 – Common Vocabulary. Final Specification, W3C ODRL Community Group. http://www.w3.org/community/odrl/two/vocab/

[ODRL-XML]

S. Guth & R. Iannella (eds). Open Digital Rights Language (ODRL) Version 2.0 – XML Encoding. Final Specification, W3C ODRL Community Group. http://www.w3.org/community/odrl/two/xml/

[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

[XML]

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/

Post Revisions: