ECM Protocol
MESSAGE FORMATS & SCHEMAS 13 MIN READ 2026.06.10

> Context Interchange JSON Schema Definition

A comprehensive specification for JSON schema definitions used in the context interchange between systems, detailing required fields, data types, and serialization standards.

Context Interchange JSON Schema Definition

1. Introduction

This document specifies the JSON schema definitions used for context interchange in ECM Protocol v1.0.0. The schema encompasses the structure, required fields, data types, and serialization standards necessary to ensure reliable and consistent data exchange between systems implementing the protocol.

Purpose and Scope

The primary objective of this document is to define the JSON schema for the ECM Protocol, which facilitates context interchange. The scope includes specifying the structural and semantic requirements for data exchanged between compliant systems. This ensures that implementations maintain interoperability and data integrity across diverse technological environments.

Requirements Coverage

The schema defined herein adheres to strict requirements for data structure compatibility, allowing seamless integration with existing systems. It incorporates comprehensive field definitions, leveraging JSON Schema Draft 2020-12 specifications, to guarantee the extensibility and validation of context data. Subsequent sections outline the protocol's requirements, serialization details, and compatibility measures.

Interoperability and Extensibility

Interoperability is paramount within ECM Protocol's context interchange framework. Consequently, this specification enforces mandatory compliance with all structural conventions defined herein. In addition, the protocol provides mechanisms for extensibility to accommodate future updates and variations in contextual data without disrupting existing implementations.

Terminology and Conventions

Key terms employed throughout this document align with the terminological standards set by ISO/IEC JTC 1/SC 32 Data Management and Interchange and the W3C's XML Schema Definition Language 1.1 (XSD). Terms such as 'MUST', 'SHOULD', 'MAY', and their negations are used as specified in RFC 2119 to denote requirement levels.

Reference to Related Standards

While this document emphasizes contextual data structures in ECM Protocol, related standards such as RFC 7159 for JSON Data Interchange Format and ISO/IEC 19505 Unified Modeling Language for data representation are referenced where applicable. Implementers SHOULD consult these standard documents for foundational understanding and context beyond ECM's specified usage.

JSON Schema Overview

The following JSON Schema fragment illustrates a simplified model for ECM context interchange. This example provides a high-level view of the core structure implemented throughout this document. Compliance with this foundational pattern is integral for successful interoperability across systems.


{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ECM Context Schema",
  "type": "object",
  "properties": {
    "contextId": {
      "type": "string",
      "description": "A unique identifier for the context instance."
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "The date and time when the context was created, in ISO 8601 format."
    },
    "data": {
      "type": "object",
      "description": "A flexible container for context-specific data elements."
    }
  },
  "required": ["contextId", "timestamp"]
}

This expandable structure supports additional contextual elements necessary for diverse applications and is adaptable to evolving use cases, assuring long-term relevance of the ECM Protocol.

2. Schema Structure

The JSON schema for context interchange is designed to encapsulate various data elements essential for ECM Protocol. The schema is defined to be extensible, allowing for future enhancements in a backward-compatible manner (see §4.5 on Compatibility & Versioning).

2.1 Context Schema Definition

The context interchange JSON schema is structured as follows:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ecmprotocol.com/schemas/context-interchange.schema.json",
  "title": "Context Interchange Schema",
  "type": "object",
  "properties": {
    "contextId": {
      "type": "string",
      "description": "A unique identifier for the context."
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "The ISO 8601 timestamp of the context generation."
    },
    "data": {
      "type": "object",
      "description": "The serialized data required for context sharing.",
      "properties": {
        "key": {
          "type": "string",
          "description": "A key for identifying the data element."
        },
        "value": {
          "type": ["string", "number", "boolean", "object", "array"],
          "description": "The value of the data element, supporting multiple types."
        }
      },
      "required": ["key", "value"]
    }
  },
  "required": ["contextId", "timestamp", "data"]
}
```html

3. Normative Requirements

The following normative requirements are established for systems implementing the context interchange schema:

  • Each context message MUST include a contextId which MUST be globally unique to prevent collisions.
  • The timestamp field MUST conform to the ISO 8601 standard to ensure temporal consistency.
  • Context data serialized in the data field MUST validate against the defined data schema, enforcing both presence and type constraints.
  • Implementations MAY extend the schema to include additional properties, but such extensions SHOULD NOT interfere with existing schema properties to maintain backward compatibility.

3.1 Unique Identification Requirements

Every context message MUST contain a contextId that is globally unique. This global uniqueness is crucial to prevent message collisions and maintain the integrity of the context information as it traverses different systems. The uniqueness MAY be achieved through Universally Unique Identifier (UUID) generation mechanisms, as specified in RFC 4122. The contextId MUST be of type string and adhere to the UUID format.


{
  "type": "object",
  "properties": {
    "contextId": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    }
  },
  "required": ["contextId"]
}

3.2 Temporal Consistency through Timestamp

The timestamp included in the context message MUST strictly conform to the ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ) to ensure temporal accuracy and consistency. It MUST be allocated in Coordinated Universal Time (UTC) to avoid discrepancies arising from regional time zone differences. The following JSON Schema fragment enforces this requirement:


{
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": ["timestamp"]
}

3.3 Schema Validation and Extension

The context data contained within the data field MUST validate against the predefined schema. This includes both presence validation and type constraint checks, ensuring that the data aligns with the expected structure for seamless processing across various systems. Schema validation tools or libraries compliant with JSON Schema Draft-07 (or later) MAY be used to facilitate this process. Implementations MAY introduce additional properties; however, they SHOULD document such extensions explicitly and MUST ensure no conflicts with existing properties to maintain compatibility.

3.4 Error Handling in Schema Validation

When validating context messages against the schema, error handling is critical. Implementations MUST generate detailed error reports that specify the nature of the validation failure, including the schema constraint violated and the data component affected. Error messages SHOULD be formatted in a standardized, machine-readable format, such as JSON for ease of automation:


{
  "error": "ValidationError",
  "message": "Property 'timestamp' is not in ISO 8601 format.",
  "path": "$.timestamp"
}

3.5 Security Considerations

Implementations MUST ensure that all context messages adhere to data integrity and confidentiality principles. Messages SHOULD be transferred over secure channels (e.g., using TLS) to protect against eavesdropping and man-in-the-middle attacks. Moreover, sensitive information within the interchange messages SHOULD be minimized, and any inclusion of sensitive data, such as PII, MUST comply with relevant data protection regulations such as GDPR.

For further details on contextual message integration and synchronization, refer to §6.2 Serialization Synchronization.

```

4. Data Serialization

The serialization format for the context interchange MUST adhere to the JSON standard as specified by RFC 8259. This ensures wide compatibility and interoperability with existing JSON libraries and tools.

4.1 Serialization Process

The serialization process MUST convert context data structures into JSON text. The serialization MUST ensure that the data conforms to the JSON data interchange syntax, facilitating seamless integration and interaction with various systems supporting JSON.

Data types such as objects, arrays, numbers, strings, true, false, and null MUST be represented using corresponding JSON representations. Key aspects of serialization include:

  • Character Encoding: JSON text MUST be encoded using UTF-8 encoding to ensure uniformity and support for international characters.
  • Data Integrity: Serialized JSON MUST preserve the integrity of the original data structure, ensuring no data loss or transformation errors occur during serialization.
  • Whitespace and Formatting: While JSON ignores whitespace outside of strings, implementers MAY include whitespace to improve human readability, but such formatting SHOULD NOT affect data interpretation.

4.2 Serialization Example

To illustrate the serialization of a context structure, consider the following example which adheres to the defined JSON schema:


{
  "contextId": "7b5f2401-cf0b-4b58-ae7c-4c6e6edf2d6e",
  "metadata": {
    "timestamp": "2023-10-12T08:30:00Z",
    "source": "sensor-102"
  },
  "data": [
    {
      "type": "temperature",
      "value": 22.5,
      "unit": "Celsius"
    },
    {
      "type": "humidity",
      "value": 45,
      "unit": "%"
    }
  ],
  "attributes": {
    "location": "Building A, Room 4"
  }
}

4.3 Error Handling

Serialization errors MUST be addressed with robust error handling protocols. If the serialization process encounters invalid data types or syntax, it MUST return an appropriate error message indicating the nature and location of the error within the data structure.

  • For instance, converting non-serializable objects (e.g., functions) should trigger an error with a clear description.
  • Errors MAY be logged for further analysis and troubleshooting while ensuring that any logging complies with applicable data protection and privacy standards.

Errors MUST NOT expose sensitive data; thus, care SHOULD be taken to ensure that error messages are both informative and compliant with security guidelines.

4.4 Security Considerations

As the JSON serialization format is used for context interchange, security risks such as data tampering or unauthorized access MUST be mitigated. Implementers SHOULD follow security best practices, including:

  • Ensuring secure transport layers like TLS for data transmission to protect against eavesdropping and man-in-the-middle attacks.
  • Implementing validation schemas to prevent injection attacks and ensure that only conforming JSON structures are processed.
  • Regularly updating software components to patch known vulnerabilities, especially those related to JSON processing libraries.

Moreover, compliance with security standards such as OWASP recommendations for API security SHOULD be considered (see OWASP API Security Project).

```html

5. Compatibility & Versioning

Additions to the schema, including new optional fields or expanded data types, are managed under the ECM Protocol's backward compatibility policy. The specification allows for non-breaking extensions, ensuring continued operability across different versions of the protocol.

5.1 Backward Compatibility

All future revisions to the JSON schema SHOULD strive to maintain backward compatibility, permitting existing implementations to function correctly without requiring immediate updates.

5.2 Versioning Strategy

The ECM Protocol utilizes semantic versioning to clearly communicate changes to the schema. The version number of the schema MUST be updated according to the following rules:

  • Major version increments indicate changes that might not be backward-compatible and may alter existing behavior.
  • Minor version increments are used for enhancements or additions that are backward-compatible.
  • Patch version increments represent bug fixes that enhance performance or correct errors without altering the API surface.

For example, a change that adds a new optional field SHOULD result in a minor version increment.

5.3 Validation and Compatibility Checks

Implementations MUST provide validation mechanisms to ensure that schema versions are compatible. This MAY include:

  • Using JSON Schema validation tools to verify conformance to the expected schema version.
  • Implementing logic to handle deprecated fields gracefully, retaining compatibility with older schema versions where possible.

A mismatched schema version SHOULD trigger a compatibility warning, advising the user of possible issues.

5.4 Deprecation Policy

In order to maintain backward compatibility, fields or features MUST NOT be removed immediately upon being deprecated. There MUST be a clearly defined deprecation timeline during which deprecated fields continue to function but may trigger warnings, offering users ample time to transition away before removal.

An example JSON schema with a deprecated field may look like the following:


{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "version": "2.5.0",
  "properties": {
    "newField": {
      "type": "string"
    },
    "deprecatedField": {
      "type": "string",
      "description": "This field is deprecated and will be removed in version 3.0.0."
    }
  },
  "additionalProperties": false
}

5.5 Error Handling for Version Mismatch

To handle potential issues arising from version mismatches:

  • Systems MUST log the occurrence of version mismatches with sufficient detail to diagnose and rectify the issues efficiently.
  • Where possible, systems SHOULD provide suggestions for upgrading or adapting schemas to ensure compatibility.

Related error handling procedures can be explored further in §4.3 Error Handling.

+------------+ +------------+ | Producer | --+-> | Consumer | +------------+ +------------+
```

6. Related Sections

For further clarification on the schema design and implementation guidelines, see §3.2 of the Core Protocol document, which outlines the foundational principles and technical constraints for constructing ECM Protocol-compliant schemas.

6.1 Core Protocol Alignment

The Core Protocol document provides essential insights into the underlying principles governing ECM Protocol-compliant schemas. It is imperative that implementers reference §3.2 of the Core Protocol to ensure adherence to specified constraints and design rationales. This alignment is crucial for maintaining interoperability across implementations and should be prioritized in the development process.

6.2 Serialization Synchronization

Section 4 of this document details the data serialization processes, including techniques for serialization, examples, error handling, and security considerations. Implementers MUST ensure synchronization between data serialization methods and schema definitions as outlined in §2. This synchronization is vital for both the efficiency and security of data interchange following ECM Protocol standards.

6.3 Backward Compatibility

Refer to §5.1 for guidelines on maintaining backward compatibility with previous protocol versions. Adhering to these guidelines ensures that systems implementing the ECM Protocol can interact seamlessly with legacy systems while leveraging updated schema features. Implementers SHOULD conduct thorough compatibility assessments to mitigate any disruption when new schema definitions are applied.

6.4 External Standards and Protocols

The ECM Protocol aligns with various external standards to promote broad adoption and compatibility. For example, JSON Schema definitions within the ECM Protocol are consistently aligned with the IETF's JSON Schema standard (draft specifications available at referencing their latest version). This alignment ensures that schema definitions are interoperable with existing JSON Schema validators.

6.5 Error Reporting and Troubleshooting

Implementation of ECM Protocol-compliant schemas SHOULD include comprehensive error reporting mechanisms, as outlined in §4.3. Error codes, debugging information, and troubleshooting steps are essential for diagnosing and resolving issues within ECM-compliant systems. Maintaining detailed logs and clear error messages can significantly enhance the efficiency of support and maintenance workflows.

6.6 Diagrammatic Representation of Data Flow

Visual representations of data flow, serialization processes, and context schema interactions are instrumental for understanding complex protocol interactions. Implementers MAY utilize standardized diagramming conventions to represent the ECM Protocol message handling, ensuring clarity and simplicity in protocol depiction. Below is an illustrative example:

ECM Schema Data Serialization

By utilizing the above guidelines and references, implementers can enhance the reliability, security, and compatibility of their ECM Protocol-compliant systems.

```

//TAGS

MESSAGE FORMATS SCHEMAS JSON CONTEXT INTERCHANGE
BACK_TO_MESSAGE FORMATS & SCHEMAS