specs

Finternet Schema Specifications

This directory contains JSON-LD schema definitions for the Finternet protocol, following JSON-LD best practices with a layered architecture pattern.

Architecture

The schema follows a core-extension pattern:

schema/
├── core/              # Core schema domain
│   └── v1/            # Version 1 of core schema
│       ├── context.jsonld # Core JSON-LD context mappings
│       ├── vocab.jsonld   # RDF vocabulary definitions
│       ├── core.yaml      # OpenAPI 3.1 schema definitions
│       └── README.md      # Core schema documentation
│
├── account/           # Account domain schema
│   ├── v1/            # Version 1 of account schema
│   │   ├── context.jsonld   # Account-specific context (imports core)
│   │   ├── vocab.jsonld     # Account vocabulary definitions
│   │   ├── attributes.yaml  # OpenAPI schema with x-jsonld annotations
│   │   └── README.md        # Account schema documentation
│   │
│   ├── account.jsonld       # Example account instance
│   └── account.schema.json  # JSON Schema validator (references v1/)
│
├── token/             # Token domain schema (UNITS)
│   ├── v1/            # Version 1 of token schema
│   │   ├── context.jsonld   # Token-specific context
│   │   ├── vocab.jsonld     # Token vocabulary definitions
│   │   ├── attributes.yaml  # OpenAPI schema with x-jsonld annotations
│   │   └── README.md        # Token schema documentation
│   │
│   ├── token.jsonld         # Example token instance
│   └── token.schema.json    # JSON Schema validator
│
├── credential/        # Credential domain schema (extends Token + W3C VC)
│   ├── v1/            # Version 1 of credential schema
│   │   ├── context.jsonld   # Credential context (imports W3C VC + token)
│   │   ├── vocab.jsonld     # Credential vocabulary definitions
│   │   ├── attributes.yaml  # OpenAPI schema with W3C VC types
│   │   └── README.md        # Credential schema documentation
│   │
│   ├── credential.jsonld    # Example credential token instance
│   └── credential.schema.json # JSON Schema validator
│
└── transaction/       # Transaction domain schema
    ├── v1/            # Version 1 of transaction schema
    │   ├── context.jsonld   # Transaction-specific context
    │   ├── vocab.jsonld     # Transaction vocabulary definitions
    │   ├── attributes.yaml  # OpenAPI schema
    │   └── README.md        # Transaction schema documentation
    │
    └── *.jsonld             # Example transaction instances

Design Principles

1. Separation of Concerns

2. JSON-LD Native

3. Strict Typing with Enumerations

4. Multiple Representations

5. Progressive Enhancement

Core Schema (v1)

Provides lean, reusable primitives for all Finternet schemas:

Generic Types

Base Classes

Design Philosophy: Core contains only truly generic primitives reusable across all entity types (Account, Token, ACL, etc.). Domain-specific types remain in their respective schemas.

Token Schema (v1)

Implements the Universal Token Specification (UNITS) for representing all types of financial assets as tokens.

Key Features

Token-Specific Types

The token schema defines comprehensive types for financial asset management:

Usage

{
  "@context": "https://finternet-io.github.io/specs/schemas/token/v1/context.jsonld",
  "@type": "FinancialProduct",
  "id": "urn:uuid:...",
  "metadata": {
    "tokenStandard": "UNITS-FT",
    "name": "USD Coin",
    "symbol": "USDC",
    "decimals": 6,
    "fungibility": "fungible",
    "valuationType": "fixed"
  },
  "data": {
    "reserveAccount": "did:web:circle.com:accounts:reserve-001",
    "jurisdiction": "US"
  },
  "claims": [
    {
      "@type": "VerifiableCredential",
      "issuer": "did:web:auditor.example",
      "credentialSubject": {
        "id": "urn:uuid:...",
        "reserveRatio": "100%"
      }
    }
  ],
  "identities": [
    {
      "id": "did:web:circle.com",
      "type": "issuer"
    },
    {
      "id": "did:web:alice.example",
      "type": "owner"
    }
  ],
  "state": {
    "status": "active",
    "supply": {
      "totalSupply": "10000000000000",
      "circulatingSupply": "8500000000000"
    }
  }
}

Transaction Schema (v1)

Implements a two-tier transaction architecture for tracking and recording token operations.

Key Features

Transaction-Specific Types

TransactionLog:

TokenTransaction:

AuditEvent (Admin-Only):

Usage

Atomic Swap Example:

{
  "@context": "https://finternet-io.github.io/specs/schemas/transaction/v1/context.jsonld",
  "@type": "TransactionLog",
  "txId": "urn:uuid:tx-002",
  "initiator": "did:web:alice.example",
  "tokenTransactions": [
    {
      "tokenTxId": "urn:uuid:tokentx-002",
      "tokenId": "usdc",
      "operation": "burn"
    },
    {
      "tokenTxId": "urn:uuid:tokentx-003",
      "tokenId": "usdt",
      "operation": "mint"
    }
  ],
  "status": "completed",
  "proofId": "urn:uuid:proof-001"
}

Credential Schema (v1)

Extends the Token schema to support W3C Verifiable Credentials as tokenized assets. Used to issue identity verification results from KYC providers.

Key Features

Credential-Specific Types

Usage

{
  "@context": "https://finternet-io.github.io/specs/schemas/credential/v1/context.jsonld",
  "@type": "CredentialToken",
  "id": "urn:uuid:...",
  "metadata": {
    "tokenStandard": "UNITS-CREDENTIAL",
    "name": "KYC Verification - PAN",
    "credentialType": "kycVerification",
    "verificationLevel": "enhanced",
    "provider": {
      "providerName": "Signzy",
      "journeyId": "PJGR095SLR"
    }
  },
  "claims": [
    {
      "@context": ["https://www.w3.org/2018/credentials/v1", "..."],
      "type": ["VerifiableCredential", "KYCCredential"],
      "issuer": "did:web:finternet.io",
      "issuanceDate": "2025-11-25T17:58:21Z",
      "credentialSubject": {
        "id": "did:web:user.example",
        "fullName": "John Doe"
      },
      "evidence": [
        {
          "type": ["IdentityEvidence"],
          "documentVerification": { "documentType": "pan", "documentValid": true },
          "biometricVerification": { "livenessVerified": true }
        }
      ]
    }
  ],
  "identities": [
    { "id": "did:web:finternet.io", "type": "issuer" },
    { "id": "did:web:user.example", "type": "subject" }
  ],
  "state": {
    "status": "active",
    "effectiveFrom": "2025-11-25T17:58:21Z"
  }
}

Account Schema (v1)

Extends core Entity to represent user and organizational accounts:

Key Features

Account-Specific Types

The account schema defines its own types that are specific to account management:

Usage

{
  "@context": "https://finternet-io.github.io/specs/schemas/account/v1/context.jsonld",
  "@type": "Account",
  "@id": "urn:uuid:...",
  "did": "did:key:...",
  "primaryAddress": {
    "identifierValue": "alice",
    "identifierDomain": "finternet"
  },
  "entityType": "PERSONAL",
  "status": "ACTIVE",
  "contactMethods": [
    {
      "type": "EMAIL",
      "value": "alice@example.com",
      "verified": true
    }
  ]
}

Extending the Schema

To create a new domain schema:

  1. Create domain directory under schema/
  2. Create version directory (e.g., v1/)
  3. Define files:
    • context.jsonld - Import core context, add domain terms
    • vocab.jsonld - Define domain classes and properties
    • attributes.yaml - OpenAPI schema with validation
    • README.md - Documentation
  4. Reference core types - Use $ref to core enumerations and types
  5. Create examples - Instance files showing usage
  6. Add validator - JSON Schema file for validation

Namespaces

Prefix Namespace Purpose
finternet https://finternet-io.github.io/specs/schemas/core/v1# Core Finternet terms
finternet https://finternet-io.github.io/specs/schemas/account/v1# Account-specific terms
finternet https://finternet-io.github.io/specs/schemas/token/v1# Token-specific terms
finternet https://finternet-io.github.io/specs/schemas/credential/v1# Credential-specific terms
vc https://www.w3.org/2018/credentials# W3C Verifiable Credentials
schema https://schema.org/ Schema.org vocabulary
didCore https://www.w3.org/ns/did/v1# W3C Decentralized Identifiers
sec https://w3id.org/security# W3C Security vocabulary
rdf http://www.w3.org/1999/02/22-rdf-syntax-ns# RDF vocabulary
rdfs http://www.w3.org/2000/01/rdf-schema# RDF Schema
xsd http://www.w3.org/2001/XMLSchema# XML Schema datatypes

Tools & Validation

JSON Schema Validation

# Validate an account instance against the schema
ajv validate -s account/account.schema.json -d account/account.jsonld

JSON-LD Processing

# Expand JSON-LD to see full URIs
jsonld expand account/account.jsonld

# Compact with custom context
jsonld compact -c account/v1/context.jsonld account/account.jsonld

RDF Conversion

# Convert to N-Triples
jsonld format -q account/account.jsonld

# Convert to Turtle
riot --output=turtle account/account.jsonld

Best Practices

  1. Always version your schemas - Use semantic versioning (v1, v2, etc.)
  2. Import, don’t duplicate - Reference core types via context import
  3. Document enumerations - Use rdfs:comment for each enum value
  4. Provide examples - Include realistic instance data
  5. Validate strictly - Use JSON Schema for runtime validation
  6. Think semantically - Map to established vocabularies when possible
  7. Use URNs for IDs - Prefer urn:uuid: for entity identifiers
  8. Enable discovery - Include proper @type and @id in all instances
  9. Follow naming conventions - Use PascalCase for class names (Account, Entity), camelCase for property names (primaryAddress, entityType)

References

License

See LICENSE file in repository root.

This site is open source. Improve this page.