Understanding the J-NRL JSON Schema
This post explains the J-NRL JSON schema in detail.
In our previous discussions about J-NRL, we've shown how it can represent various normative texts using JSON. To ensure consistency and enable validation, J-NRL employs a JSON schema. This post explains the J-NRL JSON schema in detail.
What is a JSON Schema?
A JSON schema defines the structure and constraints for JSON data. It specifies what properties are allowed, their data types, and any required values. Think of it as a "blueprint" for your JSON data.
J-NRL JSON Schema Overview
The J-NRL schema defines the structure for representing normative statements. It ensures that every J-NRL document adheres to a consistent format, making it easier to process and validate.
Here's the schema definition:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "JSON Schema for Normative Representation Language (J-NRL)",
"description": "Defines the structure for representing normative statements.",
"type": "array",
"items": {
"type": "object",
"properties": {
"normId": {
"type": "string",
"description": "A unique identifier for the normative statement."
},
"source": {
"type": "string",
"description": "Reference to the original legal or regulatory text."
},
"actor": {
"type": "object",
"description": "The entity to whom the norm applies.",
"properties": {
"type": {
"type": "string",
"description": "The type of actor (e.g., NaturalPerson, Organization, VehicleOperator)."
},
"description": {
"type": "string",
"description": "A more detailed description of the actor."
}
},
"required": [
"type"
]
},
"action": {
"type": "object",
"description": "The action regulated by the norm.",
"properties": {
"verb": {
"type": "string",
"description": "The main action verb."
},
"object": {
"type": "string",
"description": "The object of the action."
}
},
"required": [
"verb"
]
},
"deonticModality": {
"type": "string",
"enum": [
"Obligation",
"Permission",
"Prohibition"
],
"description": "The normative status of the action."
},
"triggeringEvents": {
"type": "array",
"items": {
"type": "string",
"description": "Events that trigger the applicability of the norm."
},
"description": "Events that trigger the applicability of the norm (inspired by eCRG)."
},
"condition": {
"type": "object",
"description": "The conditions under which the norm applies.",
"properties": {
"facts": {
"type": "array",
"items": {
"type": "string",
"description": "Factual circumstances for the norm's application."
}
},
"timeConstraint": {
"type": "string",
"description": "Temporal constraint on the condition."
},
"location": {
"type": "string",
"description": "Location-based constraint."
},
"constraints": {
"type": "array",
"items": {
"type": "object",
"description": "Specific constraints on entities or actions.",
"properties": {
"property": {
"type": "string",
"description": "The property being constrained."
},
"operator": {
"type": "string",
"enum": [
"==",
"!=",
">",
"<",
">=",
"<=",
"includes",
"excludes"
],
"description": "The comparison operator."
},
"value": {
"type": [
"string",
"number",
"boolean"
],
"description": "The value to compare against."
}
},
"required": [
"property",
"operator",
"value"
]
}
}
}
},
"consequence": {
"type": "object",
"description": "The legal effect or outcome of the norm.",
"properties": {
"stateChange": {
"type": "string",
"description": "Change in the state of affairs (inspired by eCRG)."
},
"sanction": {
"type": "object",
"description": "The sanction for violating the norm.",
"properties": {
"type": {
"type": "string",
"description": "Type of sanction (e.g., Fine, Imprisonment)."
},
"description": {
"type": "string",
"description": "Details of the sanction."
}
}
}
}
},
"temporalConstraints": {
"type": "object",
"description": "Temporal aspects of the norm's applicability.",
"properties": {
"deadline": {
"type": "string",
"format": "date-time",
"description": "The final date or time for an action."
},
"applicability": {
"type": "string",
"description": "The period during which the norm is in effect."
},
"exceptions": {
"type": "array",
"items": {
"type": "object",
"description": "Exceptions to the temporal constraints or the norm itself.",
"properties": {
"description": {
"type": "string",
"description": "Description of the exception."
},
"refersToNorm": {
"type": "string",
"description": "ID of another norm that this exception relates to (inspired by eCRG)."
}
},
"required": [
"description"
]
}
}
}
},
"relatedNorms": {
"type": "array",
"items": {
"type": "string",
"description": "IDs of other related normative statements (inspired by eCRG)."
},
"description": "References to other related normative statements."
}
},
"required": [
"normId",
"source",
"actor",
"action",
"deonticModality"
]
}
}
Key Components of the J-NRL Schema
Let's break down the key parts of this schema:
$schema: Specifies the JSON Schema version being used.titleanddescription: Provide human-readable information about the schema's purpose.type: "array": Indicates that a J-NRL document is an array of normative statements.items: Defines the structure of each individual normative statement within the array. Each item is oftype: "object".properties: Lists the valid properties (or "slots") for a normative statement object. Here's a breakdown of the most important ones:normId:type:"string"- Description: A unique identifier for the norm (e.g., "obligation-pay-tax").
source:type:"string"- Description: A reference to the original legal text (e.g., "Article 10, Tax Law").
actor:type:"object"- Description: The entity to whom the norm applies.
- Properties:
type:"string"(e.g., "Person", "Company").description:"string"(A more detailed description).
required:["type"](Thetypeof actor is mandatory).
action:type:"object"- Description: The action that is regulated
- Properties:
verb:"string"(e.g., "Pay", "Deliver").object:"string"(e.g., "Tax", "Goods").
required:["verb"]
deonticModality:type:"string"enum:["Obligation", "Permission", "Prohibition"]- Description: The normative status of the action.
condition:type:"object"- Description: The conditions for the norm's application.
- Properties:
facts:arrayof strings.timeConstraint:"string".location:"string".constraints:arrayof constraint objects, where each constraint has aproperty,operator, andvalue.
consequence:type:"object"- Description: The result of fulfilling or violating the norm.
- Properties:
stateChange:"string".sanction:objectwithtypeanddescription.
temporalConstraints:type:"object"- Description: Temporal aspects of the norm.
- Properties:
deadline:"string"(in date-time format).applicability:"string".exceptions:arrayof exception objects.
relatedNorms:type:"array"items:type: "string"- Description: IDs of related norms.
required: Specifies the essential properties that must be present in every normative statement object:"normId","source","actor","action", and"deonticModality".
Benefits of Using the JSON Schema
- Validation: You can use the schema to automatically validate whether a J-NRL document is well-formed. Many libraries and tools can perform this validation.
- Consistency: The schema ensures that everyone uses the same structure, avoiding ambiguity and errors.
- Documentation: The schema itself serves as documentation, clearly defining the format of J-NRL data.
- Code Generation: The schema can be used to generate code (e.g., classes or data structures) in various programming languages, simplifying the development of J-NRL processing tools.
By adhering to this JSON schema, developers can create robust and interoperable systems for working with normative texts.