Welcome

This guide is intended for data publishers that wish to disseminate structured metadata about legislation on the web using schema.org Legislation extension. It is especially targeted at stakeholders of the European Legislation Identifier (ELI) initiative, that are already engaged in the dissemination of structured data using the ELI ontology. This guide should also be useful for:

This guide assumes that the reader is comfortable with schema.org, with the JSON-LD syntax, and with legislation publishing and consolidations.

Legislation on the web, schema.org, and ELI

Why describe Legislation using schema.org ?

To share and link legislation data at web-scale, in a decentralized way.

These 2 mockups show the “dream” in terms of search use-cases around legislation in major search engines :

Legislation rich snippet

Legislation in knowledge graph

These mockups display specific structured data about the act:

These are only mockups, of course, and they do not represent a commitment of any search engine to implement this as it is depicted.

Resources

Schema.org Legislation extension is at http://schema.org/Legislation. It was derived from the ELI ontology, which itself is the result of discussions amongst 14+ Official Journals of EU Member States about how to best represent and describe legislation metadata.

Community discussions

Interested readers can find more information on the community discussions that happened when the extension proposal was submitted :

ELI ontology guides

The ELI ontology guides for publishing legislation metadata using ELI may also provide useful background information, although not targeted at schema.org :

ELI to schema.org converter

The Office of Publications of the EU has provided a conversion tool to generate schema.org markup from ELI metadata.

Overview of the schema.org metadata available to describe Legislation (and why this is insufficient)

The necessary attributes to describe legislation in schema.org are summarized in this diagram, showing how the description of legislation is mixing generic attributes available on the class CreativeWork, and specific attributes proposed for the specific description of Legislation :

Legislation schema.org diagram

This diagram gives a good overview of which properties are interesting/necessary for the description of legal acts, however it is not sufficient :

The rest of this guide captures the good practices in terms of data modeling for the description of legal acts and how to apply them in the context of the schema.org Legislation extension. It renders these good practices as an application profile of schema.org for the description of legislation. It is certainly not the only and definitive solution for the description of legislation, alternative solutions are of course possible.

Good practices for the description of Legislation in schema.org

What does schema:Legislation means ?

The schema:Legislation type in schema.org may be used to describe different things:

  1. A base act published in an official journal. This is the “birth” of a legal act.
  2. An amending act, also published in an official journal, amending the base act. This is expressed like a “diff” applied on the base act (“In the base act, point 2 of article 3 is replaced by the following : ….”)
  3. A consolidated version of the base act, as amended by one or more amending act. This is the base act, with all its “diffs” applied on it.
  4. The “abstract” act, that is the act as an intellectual work, independantly of one of its (consolidated) version. This is intuitively what we are using when writing a legal reference without specifying a version : “Council Directive (EC) 93/104 concerning certain aspects of the organisation of working time [1993] OJ L307/18 (Working Time Directive)”.
  5. An article or another subdivision inside the base act, or one of its version.

Base act, amending acts, consolidated versions, abstract act

The relation between the base act, its amending act, the resulting consolidated versions, and the abstract act is shown in the diagram below:

Relation between base act, amending act, consolidated versions and abstract act

This is the sequence of events that this diagram depicts :

  1. A base act is published in an Official Journal.
  2. Immediately, a first consolidated version of the act is produced (Consolidated act V0).
  3. A first amending act is published in the OJ.
  4. The base act and the first amending act are consolidated in Consolidated act V1
  5. A second amending act is published in the OJ.
  6. The base act, the first and second amending acts are consolidated in Consolidated act V2.

There are a few important things to note:

The relationships between these entities is as follow:

  1. The abstract act refers to its successive versions using the schema:workExample property. (in the web pages of each consolidated version, only one of these links will be present, not all).
  2. Each consolidated version of the act points to the base act and all the amending acts being consolidated in this version using the schema:legislationConsolidates property.
  3. The abstract act points to the base act that it derives from using the schema:isBasedOn property.

schema:Legislation specifies a certain number of links between Legislation entities that pertain to legal analysis, that is to the analysis of the actual content of the legal act (vs. identification properties) and how it relates to other acts. These links are (click to get the definition on schema.org website):

These links:

Articles and Subdivisions

Articles and other subdivisions are also typed as schema:Legislation. The whole act refers to its subdivisions using schema:hasPart, and subdivisions can contain other subdivisions. The usage of subdivision is not mandatory, and the data can stop at describing the whole act only.

The combination of legal analysis links and subdivisions is depicted in the below diagram:

Legal Analysis links and subdivisions

This is the content depicted in this diagram:

  1. The initial base act has 2 articles, article 1 and article 2. Hence the Consolidated Version V0 has the same structure.
  2. Modifying act 1, through its article 1, amends the article 1 of the initial act, hence the legislationAmends link points to the article 1 of the Consolidated Version V0, because it is the actual article being amended.
  3. Modifying act 1 is consolidated by the Consolidated Act V1 (link not shown for readability).
  4. Modifying act 2, through its article 1, repeals (cancels) the article 2 of the initial act, hence the legislationRepeals link points to the article 1 of the Consolidated Version V1.
  5. Modifying act 1 and 2 are consolidated by Consolidated Act V2, that contains only 1 article (because article 2 was repealed).

In addition to the legal analysis relationships described above that refer to acts in the same legal corpus, other links are provided to refer to acts of another legal corpus, typically to refer to EU directives or regulations that are transposed or implemented by EU Member States. This also covers Non-EU cases of local regulation applying a national legislation. The relations are:

Legislation in schema.org Application Profile

Act (Base act or Modifying act)

An act as published in an official journal. The description of a base act or modifying act has the same structure.

Mandatory properties for Act (Base act or Modifying act)

Property Range Card. Usage Note
@id URI 1..1 URI identifier for the act
@type fixed value Legislation 1..1 Always set the type to Legislation
name rdf:langLiteral 1..n An act may have more than one title, in case it is multilingual.
encoding Legislation file 1..n Refers to file expressing the act, in PDF, HTML, etc. and in a given language
Property Range Card. Usage Note
inLanguage xsd:string 0..n Language of the act. Use 2-letters language codes. Repeat if act is multilingual
legislationIdentifier xsd:string 0..1 Number for the act
legislationDate xsd:date 0..1 Date at which the text became an act
legislationDateVersion xsd:date 0..1  
legislationLegalForce LegalForceStatus 0..1 Can be InForce, NotInForce, PartiallyInForce
legislationType xsd:string 0..1 Type of the text, as string (law, decree, etc.)

Optional properties for Act (Base act or Modifying act)

Property Range Card. Usage Note
about xsd:string 0..n Keywords on the act, as string
alternateName xsd:string 0..n alternative or short title
datePublished xsd:date 0..1 Date of publication in the Official Journal
description xsd:string 0..n  
isPartOf PublicationIssue 0..1 The OJ issue in which the act was published
legislationCountersignedBy xsd:string 0..n  
legislationDateOfApplicability xsd:date 0..1  
legislationPassedBy xsd:string 0..n  
legislationResponsible xsd:string 0..n  
publisher Organization 0..n Usually refers to the service/administration in charge of publishing legislation in an Official Journal
spatialCoverage Place 0..n Jurisdiction, applicability area or sovereignity
temporalCoverage xsd:string 0..1 In force range of the act, from the date it was set in force to the date it was repealed. Use ISO 8601 time interval format, and use xxxx-xx-xx/.. to represent an open-ended interval for acts that are still in force.
all legal analysis properties.   0..n  
all transposition and implementation properties.   0..n  

Example

{
	"@id" : "http://country.xyz/eli/decree/1234-56/oj",
	"@type" : "Legislation",
	"name" : [
		{ "@value" : "Decree of the XXXX-XX-XX regarding...", "@language" : "en" }
		{ "@value" : "Décret du ... portant sur ...", "@language" : "fr" }
	],
	"legislationIdentifier" : "1234-56",
	"legislationType" : "Decree",
	"inLanguage" : ["fr", "en"],
	"legislationDate" : "2019-09-22",
	"datePublished" : "2019-09-23",
	"isPartOf" : {
		"@id": "http://country.xyz/official-journal/20190923",
		"@type" : "PublicationIssue",
		"name" : "Official Journal from 2019-09-23"
	},

	"encoding" : {
		...
	}
}

Act consolidated version

A given consolidated version of an act. An Act consolidated version will never be described on its own, but it will always be included in the Abstract act description inside a workExample property (see the section on Abstract act.

Mandatory properties for Act consolidated version

Property Range Card. Usage Note
@id URI 1..1 URI identifier for this consolidated version, typically including a date to identify the version
@type fixed value Legislation 1..1 Always set the type to Legislation
encoding Legislation file 1..n Refers to file expressing this act consolidated version, in PDF, HTML, etc. and in a given language
@reverse workExample Legislation (Abstract Act) 0..1 An Act version must be described within the context of an Abstract Act (the @reverse notation indicate we are expecting this entity to be the value / object of the property, and not its subject.)
Property Range Card. Usage Note
datePublished xsd:date 0..n The date at which this version was published (not to be confused with the date at which the original base act was published in the OJ)
legislationConsolidates Legislation (Base act) 0..n Points to the base act and all modifying act taken into account in this version
legislationLegalForce LegalForceStatus 0..1 Indicate the validity of that specific version of the act, as opposed the in-force status of the whole act itself. Can be InForce or NotInForce
temporalCoverage Place 0..n The validity range of this version of the act, from the date it is consolidated to the date it is replaced by a new version. Not to be confused with the in force time span of the act itself. Use ISO 8601 time interval format, and use xxxx-xx-xx/.. to represent an open-ended interval.
@reverse all legal analysis properties - 0..n Backward links from all modifying acts that refer to this version (the @reverse notation indicate we are expecting this entity to be the value / object of the property, and not its subject.)

Optional properties for Act consolidated version

Property Range Card. Usage Note
hasPart Legislation (Article or other subdivision) 0..n Points to the articles or other subdivisions in this act version
publisher Organization 0..n Usually refers to the service/administration in charge of publishing consolidated texts (could be different than the organization publishing the OJ)
text xsd:string 0..1 May contain the textual content of the act version, as a plain string
version xsd:string 0..1  

Example

{
	"@id" : "http://country.xyz/eli/decree/1234-56", 
	"@type" : "Legislation",
	"name" : [
		{ "@value" : "Decree of the XXXX-XX-XX regarding...", "@language" : "en" }
		{ "@value" : "Décret du ... portant sur ...", "@language" : "fr" }
	],
	"legislationIdentifier" : "1234-56",
	"legislationType" : "Decree",
	"inLanguage" : ["fr", "en"],
	"legislationDate" : "2019-09-22",
	"legislationLegalForce" : "InForce",
	"temporalCoverage" : "2019-09-22/..",
	"legislationDateVersion" : "2021-01-28",
	"isBasedOn" : "http://country.xyz/eli/decree/1234-56/oj",
	"workExample" : {
		"@id" : "http://country.xyz/eli/decree/1234-56/20200301",
		"@type" : "Legislation",
		"datePublished" : "2020-03-03",
		"temporalCoverage" : "2020-03-01/..",
		"legislationLegalForce" : "NotInForce",
		"legislationConsolidates" : [
			"http://country.xyz/eli/decree/1234-56/oj",
			"http://country.xyz/eli/modifyingAct/ABC",
			"http://country.xyz/eli/modifyingAct/DEF",
		],
		"text" : "...",
		"@reverse" : {
			"legislationAmends" : [
				"http://country.xyz/eli/modifyingAct/GHI",
				"http://country.xyz/eli/modifyingAct/JKL"
			]
		}
		
		"encoding" : {
			...
		}
	}
}

Abstract act

The abstract act is the one that we intuitively refer to when talking about the legislation without specifying which version we are referring to. Its metadata should contain sufficient information to be able to resolve references to this act; which precise information depends on the legal corpus.

The Abstract act will usually be used within the markup for a specific version of the act, and include one workExample to point to the version visible in the current page.

Mandatory properties for Abstract act

Property Range Card. Usage Note
@id URI 1..1 URI identifier for the abstract act. This identifier must be the same for each version of the same act.
@type fixed value Legislation 1..1 Always set the type to Legislation
name rdf:langLiteral 1..n Title of the act. An act may have more than one title, in case it is multilingual.
Property Range Card. Usage Note
inLanguage xsd:string 0..n Use 2-letters language codes. Repeat if act is multilingual
isBasedOn Legislation (Base Act) 0..n Refers to the URI of the Base Act. Although not strictly mandatory if you describe only the abstract act, and not the base act, this is highly recommended
legislationIdentifier xsd:string 0..1 Number for the act
legislationDate xsd:date 0..1 Date at which the text became an act
legislationDateVersion xsd:date 0..1  
legislationLegalForce LegalForceStatus 0..1 Can be InForce, NotInForce, PartiallyInForce
legislationType xsd:string 0..1 Type of the text, as string (law, decree, etc.)
workExample Legislation (Act version) 0..n Refers to specific versions of this legislation

Optional properties for Abstract act

Property Range Card. Usage Note
about xsd:string 0..n Keywords on the act, as string
alternateName xsd:string 0..n alternative or short title
datePublished xsd:date 0..1 Date of publication in the Official Journal
description xsd:string 0..n  
isPartOf PublicationIssue 0..1 The OJ issue in which the act was published
legislationCountersignedBy xsd:string 0..n  
legislationDateOfApplicability xsd:date 0..1  
legislationPassedBy xsd:string 0..n  
legislationResponsible xsd:string 0..n  
publisher Organization 0..n Usually refers to the service/administration in charge of publishing legislation in an Official Journal
spatialCoverage Place 0..n Jurisdiction, applicability area or sovereignity
temporalCoverage xsd:string 0..1 In force range of the act, from the date it was set in force to the date it was repealed. Use ISO 8601 time interval format, and use xxxx-xx-xx/.. to represent an open-ended interval for acts that are still in force.

Example

{
	"@id" : "http://country.xyz/eli/decree/1234-56", 
	"@type" : "Legislation",
	"name" : [
		{ "@value" : "Decree of the XXXX-XX-XX regarding...", "@language" : "en" }
		{ "@value" : "Décret du ... portant sur ...", "@language" : "fr" }
	],
	"legislationIdentifier" : "1234-56",
	"legislationType" : "Decree",
	"inLanguage" : ["fr", "en"],
	"legislationDate" : "2019-09-22",
	"legislationLegalForce" : "InForce",
	"temporalCoverage" : "2019-09-22/..",
	"legislationDateVersion" : "2021-01-28",
	"isBasedOn" : "http://country.xyz/eli/decree/1234-56/oj"
}

Legislation file

A Legislation file, or LegislationObject in schema.org naming, is the encoding of a an act, or act version, in a given language and in a given file format. An act or act version will typically be associated to different files of the same text, each in a different format and possibly a different language when the legislation is multilingual.

Mandatory properties for Legislation file

Property Range Card. Usage Note
@id URI 1..1 URI identifier for the legislation object
@type fixed value LegislationObject 1..1 Always set the type to LegislationObject
contentUrl URL 1..1 URL of the actual file
encodingFormat xsd:string 1..1 Media type as a MIME format e.g. application/pdf, text/html, application/xml
inLanguage xsd:string 1..n Language of the document. Use 2-letters language codes. In the rare case that the same document contains the act text in multiple languages, that property can be repeated at this level.
@reverse encoding Legislation (Base Act) or Legislation (Act Version) 1..1 Backward link from the base act or the act version encoded by this legislation file. (@reverse notation indicate we are expecting this entity to be the value / object of the property, and not its subject.)
Property Range Card. Usage Note
legislationLegalValue LegalValueLevel 0..1 The legal value of this file. Different files may have different legal values. Typically a digitally signed PDF have a “stronger” legal value than the HTML file of the same act. Values from stronger to weaker are DefinitiveLegalValue, AuthoritativeLegalValue, OfficialLegalValue, UnofficialLegalValue

Optional properties for Legislation file

Property Range Card. Usage Note
copyrightHolder Organization 0..1  
license URL 0..1 License URL of this file
publisher Organization 0..1 Publisher of the file

Example

{
	"@id" : "http://country.xyz/eli/decree/1234-56", 
	"@type" : "Legislation",
	"workExample" : {
		"@id" : "http://country.xyz/eli/decree/1234-56/20200301",
		"@type" : "Legislation",
		"encoding" : {
			"@id" : "http://country.xyz/eli/decree/1234-56/20200301/fr/pdf",
			"@type" : "LegislationObject",
			"inLanguage" : "fr",
			"encodingFormat" : "application/pdf",
			"contentUrl" : "http://country.xyz/wp-content/1234-56-20200301-fr.pdf",
			"legislationLegalValue" : "OfficialLegalValue",
			"license" : "...",
			"copyrightHolder" : "...",
			"publisher" : "..."
		},
		"encoding" : {
			"@id" : "http://country.xyz/eli/decree/1234-56/20200301/en/pdf",
			"@type" : "LegislationObject",
			"inLanguage" : "en",
			"encodingFormat" : "application/pdf",
			"contentUrl" : "http://country.xyz/wp-content/1234-56-20200301-en.pdf",
			"legislationLegalValue" : "OfficialLegalValue"
		},
		"encoding" : {
			"@id" : "http://country.xyz/eli/decree/1234-56/20200301/fr/html",
			"@type" : "LegislationObject",
			"inLanguage" : "fr",
			"encodingFormat" : "text/html",
			"contentUrl" : "http://country.xyz/wp-content/1234-56-20200301-fr.html",
			"legislationLegalValue" : "OfficialLegalValue"
		},
		"encoding" : {
			"@id" : "http://country.xyz/eli/decree/1234-56/20200301/en/html",
			"@type" : "LegislationObject",
			"inLanguage" : "en",
			"encodingFormat" : "text/html",
			"contentUrl" : "http://country.xyz/wp-content/1234-56-20200301-en.html",
			"legislationLegalValue" : "OfficialLegalValue"
		}
	}
}

Article or other subdivision

A subdivision inside an act, or inside an act consolidated version, typically an article.

Mandatory properties for Article or other subdivision

Property Range Card. Usage Note
name xsd:string 1..1 Display title of the article, typically “Article 2”
legislationIdentifier xsd:string 1..1 Number of the subdivision, typically article number

Recommended properties for Article or other subdivision

Property Range Card. Usage Note
@id URI 0..1 Although not strictly mandatory, it is a good practice to assign URI identifiers to subdivisions, too
hasPart Legislation (Article or other subdivision) 0..n A subdivision may contain other subdivisions
legislationLegalForce LegalForceStatus 0..1 The legal force of the article. Articles within the same act can have a different legal force. Can be InForce, NotInForce, PartiallyInForce
text xsd:string 0..1 May contain the textual content of the article, as a plain string

Optional properties for Article or other subdivision

Property Range Card. Usage Note
spatialCoverage Place 0..n Articles within the same act can have different applicability areas
temporalCoverage xsd:string 0..1 In force range of this article, from the date it was set in force to the date it was repealed. Use ISO 8601 time interval format, and use xxxx-xx-xx/.. to represent an open-ended interval
all Legal analysis properties Legislation (Act version or Article thereof) 0..n When the article is an article of a base act or a modifying act, it may have legal analysis links to act versions, or articles thereof
@reverse all Legal analysis properties Legislation (Modifying Act or Article thereof) 0..n When the article is an article of a an act version, it may have backward legal analysis links from modifying acts ot article thereof. (the @reverse notation indicate we are expecting this entity to be the value / object of the property, and not its subject.)

Example

{
	"@id" : "http://country.xyz/eli/decree/1234-56", 
	"@type" : "Legislation",
	"workExample" : {
		"@id" : "http://country.xyz/eli/decree/1234-56/20200301",
		"@type" : "Legislation",		
		"hasPart" : [
		{
			"@id" : "http://country.xyz/eli/decree/1234-56/20200301/art_1", 
			"@type" : "Legislation",
			"name" : "Article 1",
			"legislationIdentifier" : "1",
			"text" : "No person shall drive a vehicle on a section of road which is subject to a variable speed limit at a speed exceeding that indicated by a speed limit sign."
		},
		{
			"@id" : "http://country.xyz/eli/decree/1234-56/20200301/art_2", 
			"@type" : "Legislation",
			"name" : "Article 2",
			"legislationIdentifier" : "2",
			"text" : "...",
			"hasPart" : [
				...
			]
		}
	}
}
Property Range Card. Usage Note
citation CreativeWork 0..n Legal citation in the text
isBasedOn Legislation 0..n Indicates that an act relies on another, typically secondary legislation is based on primary legislation, itself based on constitution. Not to be confused with an abstract act that is based on the base act.
legislationChanges Legislation (Act version or subdivision thereof) 0..n Indicates a modification in the legal content of the act
legislationAmends Legislation (Act version or subdivision thereof) 0..n A modification in the content
legislationRepeals Legislation (Act version or subdivision thereof) 0..n Cancels a legislation or an article
legislationCommences Legislation (Act version or subdivision thereof) 0..n Sets another legislation or article into force
legislationCorrects Legislation (Act version or subdivision thereof) 0..n Indicates a correction that does not affect the legal content of the act

Transposition and implementation properties

Property Range Card. Usage Note
legislationApplies Legislation 0..n Generic link to state that an act somehow transfers another act into another legislative context
legislationTransposes Legislation 0..n Specific to EU directives transposition, with a precise, legally-binding, meaning
legislationEnsuresImplementationOf Legislation 0..n To be used for EU regulations that are not transposed, or to state that an act makes sure there is no conflict for another act to apply
sameAs Legislation (Base act) 0..n In the specific case where a legal act published in a different legal corpus is getting republished in this corpus, for example EU directives republished in national Official Journals, or national acts republished in local journals

Semantic Pitfalls

Some properties are used in different places with a slightly different meaning :