https://github.com/jsonx-org/javascript
Reference implementation of the JSONx specification for the JavaScript platform. [Work In Progress]
https://github.com/jsonx-org/javascript
Last synced: 12 months ago
JSON representation
Reference implementation of the JSONx specification for the JavaScript platform. [Work In Progress]
- Host: GitHub
- URL: https://github.com/jsonx-org/javascript
- Owner: jsonx-org
- Created: 2019-07-15T12:58:37.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2022-10-17T11:12:48.000Z (over 3 years ago)
- Last Synced: 2025-01-04T09:10:31.885Z (over 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 15.6 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# JSONx Framework for JavaScript
> **JSON Schema for the enterprise**
## Abstract
The JSONx Framework is a collection of specifications and reference implementations that provide structural and functional patterns intended to help developers work with JSON. The JSONx Framework defines the [JSON Schema Definition Language][schema], which is a schema language designed in close resemblance to the [XMLSchema❐][xmlschema] specification.
This document introduces the JSONx Framework, and presents a directory of links to its constituent parts and related resources.
### Note
_The JSONx Framework for JavaScript is work in progress, and does not yet have a functional implementation. The [JSONx Framework for Java][java], however, is fully implemented, offering a complete solution for the full spec of the [JSON Schema Definition Language][schema]._
## Table of Contents
1 [Introduction](#1-introduction)
1.1 [Conventions Used in This Document](#11-conventions-used-in-this-document)
2 [JSON Schema Definition Language][#jsd]
2.1 [Purpose](#21-purpose)
2.2 [Requirements](#22-requirements)
2.3 [Getting Started](#23-getting-started)
2.4 [JSD vs JSDx](#24-jsd-vs-jsdx)
2.5 [Specification](#25-specification)
3 [Document Validation](#3-document-validation)
3.1 [Purpose](#31-purpose)
3.2 [Requirements](#32-requirements)
3.3 [Getting Started](#33-getting-started)
3.4 [Specification](#34-specification)
4 [Contributing](#4-contributing)
5 [Special Thanks](#5-special-thanks)
6 [License](#6-license)
## 1 Introduction
The JSONx Framework was created to help developers address common problems and use-cases when working with JSON. The JSONx Framework offers structural and functional patterns that systematically reduce errors and pain-points commonly encountered when developing software that interfaces with JSON. The structural patterns are defined in the [JSON Schema Definition Language][schema], which is a programming-language-agnostic schema language to describe constraints and document the meaning, usage and relationships of the constituent parts of JSON documents. The functional patterns are reference implementations (on the Java platform) of the specification of the schema language, providing utilities that address common use-cases for applications that use JSON in one way or another. Common use-cases include:
1. Definition of a normative contract between a producer and consumer of JSON documents.
1. Validation of JSON documents conforming to a respective schema document.
1. Java class binding capabilities for JSON documents conforming to a respective schema document.
### 1.1 Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119.txt).
## 2 JSON Schema Definition Language
Describes JSON documents using schema components to constrain and document the meaning, usage and relationships of their constituent parts: value types and their content.
### 2.1 Purpose
Provide a schema language to describe normative contracts between producer and consumer ends of a protocol exchanging JSON documents.
### 2.2 Requirements
1. The schema language MUST constrain and document the meaning, usage, constraints and relationships of the constituent parts of a JSON document.
1. The schema language MUST provide meaningful and useful constraint rules for the 5 JSON value types:
`boolean`, `number`, `string`, `object`, `array`.
1. The schema language MUST support schema descriptions for any and all legal JSON documents, as specified by [RFC2119](https://www.ietf.org/rfc/rfc2119.txt).
1. The schema language MUST be free-of and agnostic-to patterns specific to any particular programming language.
1. The schema language MUST be able to describe itself.
### 2.3 Getting Started
The JSON Schema Definition Language can be expressed in 2 forms: JSD (Json Schema Document), and JSDx (JSD in XML semantics).
Create `schema.jsd` or `schema.jsdx` with the following content:
###### **JSD**
```json
{
"jx:ns": "http://www.jsonx.org/schema-0.3.jsd",
"jx:schemaLocation": "http://www.jsonx.org/schema-0.3.jsd http://www.jsonx.org/schema.jsd",
"myNumber": { "jx:type": "number", "range": "[-1,1)" },
"myString": { "jx:type": "string", "pattern": "[a-z]+" },
"myObject": {
"jx:type": "object", "properties": {
"myArray": {
"jx:type": "array", "elements": [
{ "jx:type": "boolean" },
{ "jx:type": "reference", "type": "myNumber" },
{ "jx:type": "reference", "type": "myString" },
{ "jx:type": "array", "elements": [
{ "jx:type": "boolean" },
{ "jx:type": "number", "range": "[0,100]", "scale": 0 },
{ "jx:type": "string", "pattern": "[0-9]+" },
{ "jx:type": "any", "types": "myNumber myString" } ]},
{ "jx:type": "reference", "type": "myObject" },
{ "jx:type": "any", "types": "myString myObject" }]
}
}
}
}
```
###### **JSDx**
```xml
```
_**Note:** You can use the [Converter][#converter] utility to automatically convert between JSD and JSDx._
This example defines a schema with 3 types that express the following structure:
1. Type **`myNumber`**: A `number` between the range -1 (inclusive) and 1 (exclusive).
1. Type **`myString`**: A `string` with the regex patter "[a-z]+".
1. Type **`myObject`**: An `object` that has one property:
1. "myArray": An `array` that defines a sequence of elements:
1. `boolean`
1. **`myNumber`**
1. **`myString`**
1. An `array` with the following elements:
1. `boolean`
1. An integer `number` between 0 and 100.
1. A `string` of pattern "[0-9]+"
1. Either **`myNumber`** or **`myString`**.
1. `myObject`
1. Either **`myString`** or **`myObject`**.
### 2.4 JSD vs JSDx
The JSDx format offers XML validation, and using an XML IDE like [oXygen XML Editor❐][oxygenxml] offers edit-time XML validation, such as:
When using the JSDx format with the [oXygen XML Editor❐][oxygenxml], the auto-completion features of the editor will guide you in writing the schema. With the JSDx format, the XML editor will also validate keys and keyrefs to ensure that declared types are referenced correctly.
### 2.5 Specification
_For a detailed specification of the schema language, see **[JSON Schema Definition Language][schema]**._
## 3 Document Validation
Provide a way for JSON documents whose structure is expressed in the [JSON Schema Definition Language][schema] to be validated.
### 3.1 Purpose
Provide a Validator for the validation of JSON documents against a JSD or JSDx.
### 3.2 Requirements
1. The Validator MUST support the full scope of the [JSON Schema Definition Language][schema].
1. The Validator MUST produce clear and useful error messages that identify the exact location of the error when validation errors are encountered.
1. The Validator MUST be interoperable in Node.js and the browser.
1. The Validator MUST be straightforward, intuitive, and resilient to human error.
### 3.3 Getting Started
Coming soon.
### 3.4 Specification
Coming soon.
## 4 Contributing
Pull requests are welcome. For major changes, please [open an issue](../../issues) first to discuss what you would like to change.
Please make sure to update tests as appropriate.
## 5 Special Thanks
[](https://www.ej-technologies.com/products/jprofiler/overview.html)
_Special thanks to [EJ Technologies](https://www.ej-technologies.com/) for providing their award winning Java Profiler ([JProfiler](https://www.ej-technologies.com/products/jprofiler/overview.html)) for development of the JSONx Framework._
## 6 License
This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.
[#converter]: #532-converter
[#jsd]: #3-json-schema-definition-language
[java]: ../../../java
[schema]: ../../../schema
[oxygenxml]: https://www.oxygenxml.com/xml_editor/download_oxygenxml_editor.html
[xmlschema]: http://www.w3.org/2001/XMLSchema