nfh-trust-labs · Anusree-J · Apr 8, 2026 · Apr 7, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,50 @@
+# Contributing
+
+Thanks for helping improve OpenCred's credential schemas. This repo is small and conservative on purpose: schemas published here are referenced by credentials in the wild, so the bar for changes is high.
+
+## Adding a new schema
+
+1. **Pick a name.** Lowercase, hyphenated (`salary-slip`, not `SalarySlip`). Singular noun. Match the credential's primary subject.
+2. **Create the directory:** `schemas/<name>/v1/`.
+3. **Write the JSON Schema** at `schemas/<name>/v1/schema.json`:
+   - Use JSON Schema draft-07 or draft 2020-12 (be consistent within a schema).
+   - Set `$id` to the raw URL: `https://raw.githubusercontent.com/nfh-trust-labs/opencred-vc-schemas/main/schemas/<name>/v1/schema.json`.
+   - Include `title` and `description`.
+   - Mark required fields explicitly under `required`.
+   - Document each property with `description`.
+   - Default `additionalProperties` to `true` unless you have a reason to lock it down.
+4. **Write a README** at `schemas/<name>/v1/README.md` that includes:
+   - The schema URL
+   - A required-fields table and an optional-fields table
+   - At least one realistic example
+5. **Optional**: add a `context.jsonld` if the credential needs JSON-LD term mappings, and an `example.json` with a full example credential.
+
+## Revising an existing schema
+
+Schemas published here are **immutable**. Once a `v<n>/schema.json` URL is referenced by a credential in the wild, the file at that URL must keep working forever.
+
+| Change | Action |
+|---|---|
+| Typo in `description`, README clarification, comment | Edit in place — does not change validation behavior |
+| Tightening validation (new required field, narrower constraint) | **Breaking** — publish as `v<n+1>` |
+| Loosening validation (new optional field, wider constraint) | **Non-breaking** — still publish as `v<n+1>`, do **not** mutate `v<n>` |
+| Renaming or removing a field | **Breaking** — publish as `v<n+1>` |
+
+In all cases of structural change, create a new version directory and leave the previous one untouched.
+
+## Pull request checklist
+
+- [ ] Schema validates against its declared `$schema` meta-schema
+- [ ] Example in the README validates against the schema
+- [ ] `$id` matches the file's raw URL exactly
+- [ ] README documents required + optional fields and includes an example
+- [ ] If revising, the change respects the immutability policy above
+- [ ] PR description explains the use case for the schema or change
+
+## Where this gets used
+
+These schemas are consumed by:
+
+- **OpenCred Desktop & Docker** — `credentialSchema` references in issued credentials
+- **Verifiers** — schema validation during VC verification
+- **Issuers using OpenCred templates** — built-in template forms map to these schemas
diff --git a/README.md b/README.md
@@ -1,27 +1,94 @@
-# Verifiable Credential Schemas
+# OpenCred Verifiable Credential Schemas
 
-A collection of schemas for Verifiable Credentials (VCs), aligned with [Schema.org](https://schema.org) vocabulary wherever applicable.
+JSON Schemas for Verifiable Credentials (VCs) used by [OpenCred](https://github.com/nfh-trust-labs/opencred) and the broader trust-services ecosystem. Each schema is interoperable, versioned, and immutable once published.
 
-## Overview
+## Available schemas
 
-This repository maintains JSON-LD schemas for various types of verifiable credentials. Each schema is designed to be:
+| Credential | Latest | Schema URL |
+|---|---|---|
+| Education | v1 | [schemas/education/v1/schema.json](schemas/education/v1/schema.json) |
+| Employment | v1 | [schemas/employment/v1/schema.json](schemas/employment/v1/schema.json) |
+| Identity | v1 | [schemas/identity/v1/schema.json](schemas/identity/v1/schema.json) |
+| Health | v1 | [schemas/health/v1/schema.json](schemas/health/v1/schema.json) |
+| Business | v1 | [schemas/business/v1/schema.json](schemas/business/v1/schema.json) |
+| Salary Slip | v1 | [schemas/salary-slip/v1/schema.json](schemas/salary-slip/v1/schema.json) |
+| Electricity (Customer) | v1 | [schemas/electricity/v1/schema.json](schemas/electricity/v1/schema.json) |
 
-- **Interoperable**: Based on Schema.org vocabulary standards
-- **Extensible**: Custom properties for domain-specific needs
-- **Semantic**: Rich, machine-readable metadata using JSON-LD
-- **Verifiable**: Compatible with W3C Verifiable Credentials standards|
+## URL pattern
 
-All schemas in this repository prioritize alignment with Schema.org vocabulary:
+Every schema is reachable at a stable raw URL:
+
+```
+https://raw.githubusercontent.com/nfh-trust-labs/opencred-vc-schemas/main/schemas/<name>/v<version>/schema.json
+```
+
+This URL is also the schema's `$id`, so JSON Schema processors can resolve it directly. OpenCred references these URLs in the W3C VC `credentialSchema` field.
+
+## Repository layout
+
+```
+schemas/
+└── <credential-name>/
+    └── v<version>/
+        ├── schema.json     # JSON Schema (draft-07 or 2020-12)
+        ├── README.md       # field reference + example
+        ├── context.jsonld  # JSON-LD context (optional)
+        └── example.json    # example credential subject (optional)
+```
+
+## Versioning policy
+
+- Each schema version is **immutable** once merged. Bug fixes that don't change the data shape are allowed; anything else requires a new version.
+- **Breaking changes** → publish under a new version directory (`v2`, `v3`, …) and keep older versions in place.
+- **Non-breaking additions** (new optional properties, looser constraints) — bump the directory version. Don't mutate existing files.
+- Once a credential is in the wild referencing `…/v1/schema.json`, that URL must keep working forever.
+
+## Using a schema
+
+### From the command line
+
+```bash
+curl https://raw.githubusercontent.com/nfh-trust-labs/opencred-vc-schemas/main/schemas/education/v1/schema.json
+```
+
+### From a W3C Verifiable Credential
+
+```json
+{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1"
+  ],
+  "type": ["VerifiableCredential", "EducationCredential"],
+  "credentialSchema": {
+    "id": "https://raw.githubusercontent.com/nfh-trust-labs/opencred-vc-schemas/main/schemas/education/v1/schema.json",
+    "type": "JsonSchemaValidator2018"
+  },
+  "issuer": "did:web:example.org",
+  "issuanceDate": "2026-04-07T00:00:00Z",
+  "credentialSubject": {
+    "id": "did:example:subject",
+    "name": "Jane Doe",
+    "degree": "Bachelor of Science in Computer Science",
+    "institution": "University of Example",
+    "dateConferred": "2024-06-15"
+  }
+}
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add or revise a schema.
 
 ## Resources
 
-- [Schema.org Documentation](https://schema.org)
-- [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model/)
+- [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/)
+- [JSON Schema](https://json-schema.org/)
 - [JSON-LD 1.1](https://www.w3.org/TR/json-ld11/)
+- [Schema.org](https://schema.org)
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT — see [LICENSE](LICENSE).
 
 ## Maintainer
 

diff --git a/energy credentials/readme.md b/energy credentials/readme.md
diff --git a/schemas/business/v1/README.md b/schemas/business/v1/README.md
@@ -0,0 +1,29 @@
+# Business Credential — v1
+
+JSON Schema for an organization incorporation credential.
+
+## URL
+
+```
+https://raw.githubusercontent.com/nfh-trust-labs/opencred-vc-schemas/main/schemas/business/v1/schema.json
+```
+
+## Required fields
+
+| Field | Type | Format | Notes |
+|---|---|---|---|
+| `name` | string | — | Legal name of the organization |
+| `registrationNumber` | string | — | Registration number assigned by the authority |
+| `jurisdiction` | string | — | ISO 3166-1 / ISO 3166-2 code recommended |
+| `incorporationDate` | string | `date` | ISO 8601 |
+
+## Example credential subject
+
+```json
+{
+  "name": "Acme Corp Pvt Ltd",
+  "registrationNumber": "U12345KA2020PTC123456",
+  "jurisdiction": "IN-KA",
+  "incorporationDate": "2020-03-15"
+}
+```
diff --git a/schemas/business/v1/schema.json b/schemas/business/v1/schema.json
@@ -0,0 +1,31 @@
+{
+  "$id": "https://raw.githubusercontent.com/nfh-trust-labs/opencred-vc-schemas/main/schemas/business/v1/schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Business Credential",
+  "description": "Verifiable credential attesting that an organization is incorporated in a particular jurisdiction under a specific registration number.",
+  "type": "object",
+  "required": ["name", "registrationNumber", "jurisdiction", "incorporationDate"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Legal name of the organization."
+    },
+    "registrationNumber": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Registration number assigned by the registering authority."
+    },
+    "jurisdiction": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Jurisdiction of incorporation, recommended as an ISO 3166-1 / ISO 3166-2 code (e.g. \"IN\", \"US-DE\")."
+    },
+    "incorporationDate": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO 8601 date (YYYY-MM-DD) on which the organization was incorporated."
+    }
+  },
+  "additionalProperties": true
+}
diff --git a/schemas/education/v1/README.md b/schemas/education/v1/README.md
@@ -0,0 +1,32 @@
+# Education Credential — v1
+
+JSON Schema for an academic qualification credential.
+
+## URL
+
+```
+https://raw.githubusercontent.com/nfh-trust-labs/opencred-vc-schemas/main/schemas/education/v1/schema.json
+```
+
+## Required fields
+
+| Field | Type | Format | Notes |
+|---|---|---|---|
+| `name` | string | — | Full name of the credential subject |
+| `degree` | string | — | The academic qualification conferred |
+| `institution` | string | — | Conferring institution's legal name |
+| `dateConferred` | string | `date` (ISO 8601) | Date the qualification was conferred |
+
+`additionalProperties: true` — issuers may include extra fields (transcript URLs, GPA, honors, etc.) without breaking conformance.
+
+## Example credential subject
+
+```json
+{
+  "name": "Jane Doe",
+  "degree": "Bachelor of Science in Computer Science",
+  "institution": "University of Example",
+  "dateConferred": "2024-06-15",
+  "honors": "magna cum laude"
+}
+```
diff --git a/schemas/education/v1/schema.json b/schemas/education/v1/schema.json
@@ -0,0 +1,31 @@
+{
+  "$id": "https://raw.githubusercontent.com/nfh-trust-labs/opencred-vc-schemas/main/schemas/education/v1/schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Education Credential",
+  "description": "Verifiable credential attesting that a person has been conferred an academic qualification by an institution.",
+  "type": "object",
+  "required": ["name", "degree", "institution", "dateConferred"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Full name of the person to whom the credential is issued."
+    },
+    "degree": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The academic qualification conferred (e.g. \"Bachelor of Science in Computer Science\")."
+    },
+    "institution": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Legal name of the institution that conferred the qualification."
+    },
+    "dateConferred": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO 8601 date (YYYY-MM-DD) on which the qualification was conferred."
+    }
+  },
+  "additionalProperties": true
+}