Skip to content

Commit f3a2fd8

Browse files
kostyshkostysh
committed
added documentation; updated orgVc schema
1 parent 51d244c commit f3a2fd8

File tree

10 files changed

+1013
-134
lines changed

10 files changed

+1013
-134
lines changed

Diff for: ‎README.md

+5-85
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,25 @@
11
![npm](https://img.shields.io/npm/v/@windingtree/org.json-schema) [![NPM Package](https://github.com/windingtree/org.json-schema/actions/workflows/tests.yml/badge.svg)](https://github.com/windingtree/org.json-schema/actions/workflows/tests.yml)
22

3-
## Version 1.0.0-beta.*
3+
## Documentation
44

5-
- Updated DID format that now supports multichain ORGiD:
6-
7-
```
8-
did:orgid:4:0x94bf5a57b850a35b4d1d7b59f663ce3a8a76fd9928ef2067cc772fc97fb0ad75
9-
^ network Id
10-
```
11-
> `4` - Ethereum Rinkeby ChainID according to [https://chainlist.org/](https://chainlist.org/)
12-
13-
- Added ORG.JSON VC schema - a cryptographically signed version of ORG.JSON
14-
- ORG.JSON VC schema extended with NFT-specific properties to support ORGiD NFT meta-data feature
15-
- ORG.JSON schema extended with `capabilityDelegation` definition
16-
- `trustAssertions` definition in the ORG.JSON schema is extended with support for Trust Assertion Credential
17-
- Added separate Trust Assertion Credential schema
18-
- Added typescript types which are can be imported from the `types` directory of the package as following
19-
20-
```typescript
21-
import type { ORGJSON } from '@windingtree/org.json-schema/types/org.json';
22-
```
23-
24-
The whole list of available types definitions:
25-
26-
- `/types/org.json`
27-
- `/types/orgVc`
28-
- `/types/vc`
29-
- `/types/nft`
30-
- `/types/trustAssertion`
31-
32-
The whole list of json schemas that can be imported from the package:
33-
34-
- `org`
35-
- `orgVc`
36-
- `vc`
37-
- `nft`
38-
- `trustAssertion`
39-
40-
## Version 0.5.0 new features and updates
41-
42-
This version of the ORG.JSON schema should be used with new version of the ORGiD protocol (2.0).
43-
44-
- `publicKey` property is renamed to `verificationMethod` because of deprecation in the standard
45-
- Added: `verificationMethod.publicKeyJwk` property
46-
- Added: `verificationMethod.blockchainAccountId`
47-
48-
`blockchainAccountId` is a string value of the public key in following format:
49-
50-
```
51-
0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb@eip155:1
52-
^ ^ ^ ^
53-
1 2 3 4
54-
55-
1. account address (public key)
56-
2. delimiter of the key and its standard
57-
3. the standard there described a type of the blockchain and network identifiers. In this case [the Ethereum blockchain](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md)
58-
4. the blockchain network code. According to the standard 1 is the `Ethereum mainnet`
59-
```
60-
61-
- Added property `publicKey.publicKeyRevocation` to add ability of a key revocation handling
62-
- `trust.assertions` moved to the top level as `trustAssertions`
63-
- `trust.credentials` moved to the top level as `credentials`
64-
- Added optional `legalEntity.organizationalUnits` property that be a list of organizational units dids
65-
- Added optional `organizationalUnit.parentOrganization` property that be a link to the parent organization
66-
- Added top-level `person` property to add ORG.JSON ability to handle personal profiles
67-
- Definitions `CryptoETHAddress` and `CryptoBTCAddress` are replaced with single definition `BlockchainAccountId` which is standardised by the DID specification and able to handle all types of blockchain accounts
68-
- From now schema is building from multiple files. VC schemes are moved to separate file
69-
- Along with the schema file now is provided a file with typescript definitions
70-
71-
## Version 0.4.0 breaking change
72-
73-
- `legalEntity.legalIdentifier` is renamed to `legalEntity.registryCode`
74-
75-
If you are want to use an old term you should define s specific `schemaVersion` (0.3.4) in your `org.json` file overwise your `org.json` will throw a warning during validation.
76-
77-
## ORG.JSON Schema
78-
79-
ORG.JSON is a data format based on the [json-schema](http://json-schema.org/specification.html) specification used for describing organizations of all types: commercial firms, NGOs, even organizations that aren't incorporated (like [W3C](https://www.w3.org/Consortium/facts#org), for example).
80-
81-
The goal behind ORG.JSON is to provide correct and truthful snapshot of an organization, sufficient to represent its subject in any online transaction.
82-
83-
An ORG.JSON file may describe a legal entity, an organizational unit, or both at the same time. Legal entity may have zero or any number of units. Units can't exist on their own, they must belong to a legal entity.
84-
85-
While "legal entity" is self-explanatory, "units" may represent a wide range of company's structural parts: departments (accounting or legal department), business locations (in case the same legal entity operates a few different stores), etc. We intentionally made the "unit" concept flexible. Relationship between a legal entity and its units is reflected in the [ORGiD Registry](https://github.com/windingtree/org.id) smart contract.
5+
[ORG.JSON schemas documentation](./docs/index.md).
866

877
## Examples
888

899
- [legal entity](examples/legal-entity.json)
9010
- [organizational unit](examples/unit.json)
9111
- [real-life examples](https://github.com/windingtree/orgids)
9212

93-
## Usage
13+
## Setup
9414

9515
### NPM package
9616

9717
```sh
98-
npm i @windingtree/org.json-schema
18+
yarn add @windingtree/org.json-schema@1.0.0-beta.5
9919
```
10020
## JSON Schema Specification
10121

102-
This will generate a JSON Schema specification file in the `dist` directory:
22+
This will generate a JSON Schema specification file and Typescript typings in the `dist` directory:
10323

10424
```bash
10525
yarn build

Diff for: ‎docs/index.md

+80
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Validation schemas
2+
3+
The package `@windingtree/org.json-schema` provides a following set of validation schemas based on [json-schema](http://json-schema.org/specification.html) standard.
4+
5+
- `ORG.JSON`: base ORG.JSON schema
6+
- `ORGiD VC`: generic verifiable credential schema
7+
- `ORG.JSON VC NFT`: verifiable credential with ORG.JSON subject and NFT extension
8+
- `Trust Assertion Credential`: verifiable credential with Trust Assertion subject
9+
- `NFT Metadata`: base NFT metadata schema
10+
11+
## Installing the package
12+
13+
```bash
14+
yarn add @windingtree/[email protected]
15+
```
16+
17+
## Import of schemas
18+
19+
```typescript
20+
import {
21+
org as orgJsonSchema,
22+
vc as verifiableCredentialSchema,
23+
orgVc as orgJsonVcNftSchema,
24+
trustAssertion as trustAssertionSchema,
25+
nft as nftMetaDataSchema
26+
} from '@windingtree/org.json-schema';
27+
```
28+
29+
## Using schema for a data validation
30+
31+
> For the validation the ready-made `validateWithSchemaOrRef` utility from the `@windingtree/org.id-utils` package can used. Under the hood this utility is uses a powerful [`ajv`](https://github.com/ajv-validator/ajv) package.
32+
33+
```typescript
34+
import type { ORGJSON } from '@windingtree/org.json-schema/types/org.json';
35+
import { org as orgJsonSchema } from '@windingtree/org.json-schema';
36+
import { object } from '@windingtree/org.id-utils';
37+
38+
export interface OrgJsonValidatorConfig {
39+
schema: ORGJSON;
40+
path: string;
41+
}
42+
43+
const orgJson = { /* ... */ }; // raw data object
44+
45+
const validationResult = object.validateWithSchemaOrRef(
46+
orgJsonSchema,
47+
'', // empty because we do not use a specific reference from the schema
48+
orgJson as ORGJSON
49+
);
50+
51+
if (validationResult !== null) {
52+
throw new Error(
53+
`Validation error: ${validationResult}`
54+
);
55+
}
56+
```
57+
58+
## Typings
59+
60+
> Each schema definition has a huge subset of children schemas that can be imported as a separate type.
61+
> Below you can see examples of import of major types. To get detailed information about all available types please review types definition files using your IDE.
62+
63+
```typescript
64+
import type { ORGJSON } from '@windingtree/org.json-schema/types/org.json';
65+
import type { ORGiDVC } from '@windingtree/org.json-schema/types/vc';
66+
import type { ORGJSONVCNFT } from '@windingtree/org.json-schema/types/orgVc';
67+
import type { TrustAssertionCredential } from '@windingtree/org.json-schema/types/trustAssertion';
68+
import type { NFTMetadata } from '@windingtree/org.json-schema/types/';
69+
```
70+
71+
## Schemas
72+
73+
- [ORG.JSON schema](org-json.md)
74+
- [ORGiD VC schema](vc.md)
75+
- [ORG.JSON VC NFT schema](org-json-vc-nft.md)
76+
77+
78+
79+
80+

Diff for: ‎docs/org-json-vc-nft.md

+144
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# ORG.JSON VC NFT schema
2+
3+
DID documents that are built on the base of ORG.JSON specification to be verifiable must be protected from unauthorised changes with the usage of the verifiable credential method.
4+
5+
The ORGiD SDK has a function for the creation of VC (`createVc`) that accepts adding of DID documents as a credential subject for VC. Also, because every ORGiD has to provide NFT metadata to be a valid NFT this VC creation function also provides a method of adding such metadata.
6+
7+
A digital document created by this function will be a valid VC document and NFT metadata source that can be validated using the schema proposed by this package.
8+
9+
The example of the VC with DID document as a credential subject and NFT metadata:
10+
11+
```json
12+
{
13+
"@context": [
14+
"https://www.w3.org/2018/credentials/v1",
15+
"https://raw.githubusercontent.com/windingtree/org.json-schema/feat/new-orgid/src/context.json"
16+
],
17+
"id": "c48aba97-c92b-4189-8546-184112f0ebff", // <-- unique credential Id
18+
"issuer": "did:orgid:4:0x57b...ad94", // <-- credential issuer
19+
"type": [
20+
"VerifiableCredential", // <-- base credential type
21+
"OrgJson" // <-- ORG.JSON VC type
22+
],
23+
"issuanceDate": "2021-06-03T13:20:06.398Z",
24+
25+
// time restrictions (from, until, expire)
26+
"validFrom": "2021-06-04T00:00:00.000Z",
27+
"validUntil": "2021-12-04T00:00:00.000Z",
28+
"expirationDate": "2022-01-01T00:00:00.000Z",
29+
30+
"credentialSubject": { // ORG.JSON as credential subject
31+
"id": "did:orgid:4:0x57b...ad94",
32+
"created": "2021-03-03T13:20:06.398Z",
33+
"updated": "2021-04-03T13:20:06.398Z",
34+
"verificationMethod": [
35+
{
36+
"id": "did:orgid:4:0x57b...ad94#key1",
37+
"type": "EcdsaSecp256k1VerificationKey2019",
38+
"controller": "did:orgid:4:0x57b...ad94",
39+
"blockchainAccountId": "0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb@eip155:4"
40+
}
41+
],
42+
"legalEntity": {
43+
"legalName": "Acme, Corp.",
44+
"alternativeName": "Acme",
45+
"registryCode": "US12345567",
46+
"identifiers": [
47+
{
48+
"type": "IATA",
49+
"value": "123456"
50+
}
51+
],
52+
"legalType": "GmBH",
53+
"registeredAddress": {
54+
"country": "CZ",
55+
"subdivision": "71",
56+
"locality": "Jihlava",
57+
"postalCode": "71354",
58+
"streetAddress": "3150 Main St.",
59+
"premise": "STE 100"
60+
},
61+
"locations": [
62+
{
63+
"name": "Main Office",
64+
"description": "This is our main office",
65+
"address": {
66+
"country": "CZ",
67+
"subdivision": "71",
68+
"locality": "Jihlava",
69+
"postalCode": "71354",
70+
"streetAddress": "3150 Main St.",
71+
"premise": "STE 100",
72+
"gps": "50.087070,14.417210",
73+
"geocodes": [
74+
{
75+
"type": "olc",
76+
"value": "3CQ9+F2 Prague"
77+
},
78+
{
79+
"type": "what3words",
80+
"value": "printers.torn.images"
81+
}
82+
]
83+
},
84+
"openingHours": [
85+
{
86+
"weekDay": "mon,tue,wed",
87+
"hours": "9:00-18:00"
88+
},
89+
{
90+
"weekDay": "fri",
91+
"hours": "10:00-16:00"
92+
}
93+
],
94+
"contacts": [
95+
{
96+
"function": "Reception",
97+
"name": "John Smith",
98+
"phone": "+1234567890",
99+
"email": "[email protected]",
100+
"messengers": [
101+
{
102+
"type": "whatsapp",
103+
"value": "+1234567890"
104+
},
105+
{
106+
"type": "telegram",
107+
"value": "acme.ny.reception"
108+
},
109+
{
110+
"type": "viber",
111+
"value": "+1234567890"
112+
}
113+
]
114+
}
115+
]
116+
}
117+
],
118+
"contacts": [
119+
{
120+
"function": "Customer Service",
121+
"name": "John Smith",
122+
"phone": "+1234567890",
123+
"email": "[email protected]"
124+
}
125+
]
126+
}
127+
},
128+
129+
// NFT metadata
130+
"name": "Acme",
131+
"description": "Acme, Corp.",
132+
"image": "https://examle.com/path/to/image.png",
133+
"external_url": "https://examle.com",
134+
135+
// VC proof
136+
"proof": {
137+
"type": "EcdsaSecp256k1Signature2019", // <-- proof signature cryptographic suite
138+
"created": "2021-06-03T13:20:06.398Z",
139+
"proofPurpose": "assertionMethod",
140+
"verificationMethod": "did:orgid:4:0x57b...ad94#key1", // <-- verification method
141+
"jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..." // <-- proof signature
142+
}
143+
}
144+
```

0 commit comments

Comments
 (0)