9 Validation

9.0 Overview

Validation ensures that OSIRIS documents conform to the specification and can be reliably consumed by implementations. This chapter defines validation requirements at three levels: structural (JSON schema compliance), semantic (referential integrity and constraint checking) and domain (type and property conventions).

Purpose of validation:

• Quality assurance: Ensures producers emit well-formed documents
• Interoperability: Guarantees consumers can parse documents safely
• Debuggability: Provides clear error messages when issues occur
• Forward compatibility: Enables graceful handling of unknown extensions

Who should validate:

• Producers SHOULD validate documents before emission to catch errors early
• Consumers MUST validate documents at an appropriate level before processing
• Tools MAY provide validation services for OSIRIS documents

9.1 JSON Schema

9.1.1 Schema purpose

The OSIRIS JSON Schema formally defines the document structure, data types and constraints that MUST be satisfied by all OSIRIS documents. The schema provides structural validation: it verifies that:

• Documents are syntactically valid JSON format
• Required fields are present
• Field types are correct (string, object, array, etc.)
• Field values match defined patterns (e.g. version format, type naming)
• Array elements conform to expected structures

The complete JSON Schema is provided in Appendix A (JSON Schema Definition).

9.1.2 Schema location

The canonical JSON Schema for OSIRIS v1.0 is versioned in the OSIRIS repository under schema/v1.0/ and is published for consumption at:

https://osirisjson.org/schema/v1.0/osiris.schema.json

Examples in Chapter 10 are intended to conform to this canonical schema. OSIRIS documents SHOULD reference the schema using the $schema field at the top level:

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": { ... },
  "topology": { ... }
}

Consumers SHOULD validate documents against the referenced schema. Producers MAY include the $schema field to enable automatic validation by schema-aware tools.

9.1.3 Schema validation tools (non-normative)

OSIRIS is intended to be validated locally by default to preserve privacy. Implementations SHOULD avoid uploading infrastructure inventories or topology snapshots to remote services.

The following validation tools are RECOMMENDED reference implementations. They are non-normative and do not affect the OSIRIS specification itself.

VS Code validator (recommended)

A VS Code extension provides the best developer experience and privacy model:

• Runs entirely on the user’s machine (offline, no upload)
• Highlights issues inline (squiggles, diagnostics, quick fixes)
• Supports validation levels (e.g. basic schema, semantic rules, strict mode)
• Can explain errors by rule ID and link to the relevant spec section

Command-line validators (CI / automation)

Command-line validators are useful for CI pipelines and automated exports:

• Validate files and directories (osiris validate <file|dir>)
• Output machine-readable results (--format json) for CI parsing
• Support validation levels and strictness options

Web validators (optional, client-side)

A web-based validator can be provided for convenience and demos, but SHOULD run client-side in the browser to avoid transmitting sensitive data.

If a remote validation API is offered, it MUST be opt-in and clearly documented as server-side processing.

[!NOTE] Implementations SHOULD keep validator logic consistent across tools by reusing a shared validation engine where possible (e.g. a common library that performs JSON Schema checks and OSIRIS semantic rule checks).

9.1.4 Schema conformance requirements

All OSIRIS v1.0 documents MUST conform to the JSON Schema defined in Appendix A. Producers MUST emit documents that pass schema validation. Consumers MUST reject documents that fail structural validation or provide clear diagnostic messages identifying validation failures.

Structural validation is non-negotiable: Documents that fail JSON Schema validation are malformed and MUST NOT be processed by consumers except for diagnostic or debugging purposes.

9.1.5 Schema extensibility

The JSON Schema permits unknown fields in objects where extensibility is expected (top-level, metadata, resources, connections, groups, properties, extensions). This ensures forward compatibility when:

• New OSIRIS versions introduce fields
• Producers include custom metadata
• Extensions add vendor-specific data

Consumers MUST accept documents with unknown fields that pass schema validation. The schema uses "additionalProperties": true in extensible objects to permit forward-compatible evolution.

9.2 Minimum required fields (baseline interoperability)

This section enumerates required fields at each level of an OSIRIS document. Required fields MUST be present and MUST contain values of the correct type. Missing or null required fields constitute validation errors.

9.2.1 Top-level required fields

Every OSIRIS document MUST be a JSON object containing:

Validation rules:

• V-DOC-001: Document MUST be a JSON object (not array, string, number, etc.)
• V-DOC-002: Document MUST contain version, metadata and topology fields
• V-DOC-003: version MUST be a string matching ^\d+\.\d+\.\d+$ (SemVer format)
• V-DOC-004: For OSIRIS documents, version MUST be "1.0.0" or later v1.x.y versions

Valid example:

{
  "version": "1.0.0",
  "metadata": {
    "timestamp": "2026-01-01T10:30:00Z"
  },
  "topology": {
    "resources": []
  }
}

Invalid examples:

// Missing version field
{
  "metadata": { "timestamp": "2026-01-01T10:30:00Z" },
  "topology": { "resources": [] }
}

// Invalid version format missing patch version
{
  "version": "1.0",
  "metadata": { "timestamp": "2026-01-01T10:30:00Z" },
  "topology": { "resources": [] }
}

// Not an object (array)
[
  { "version": "1.0.0", ... }
]

9.2.2 Metadata required fields

The metadata object MUST contain:

Validation rules:

• V-META-001: Metadata object MUST contain timestamp field
• V-META-002: timestamp MUST be a valid ISO 8601 timestamp with timezone designator
• V-META-003: timestamp MUST include date, time and timezone (Z or offset like +00:00)

Valid timestamps:

"timestamp": "2026-01-01T10:30:00Z"              // UTC
"timestamp": "2026-01-01T10:30:00+00:00"         // UTC with offset
"timestamp": "2026-01-01T05:30:00-05:00"         // Eastern Time
"timestamp": "2026-01-01T11:30:00+01:00"         // Central European Time

Invalid timestamps:

"timestamp": "2026-01-01"                        // Missing time
"timestamp": "2026-01-01T10:30:00"               // Missing timezone
"timestamp": "2026-01-01 10:30:00Z"              // Invalid separator
"timestamp": "Jan 1, 2026"                       // Wrong format

Recommended fields (OPTIONAL but encouraged):

• generator.name (string): Name of generating tool
• generator.version (string): Version of generating tool
• scope (object): Description of what infrastructure is represented

9.2.3 Topology required fields

The topology object MUST contain:

Validation rules:

• V-TPGY-001: Topology object MUST contain resources field
• V-TPGY-002: resources MUST be an array (may be empty: [])
• V-TPGY-003: If present, connections MUST be an array
• V-TPGY-004: If present, groups MUST be an array

Minimal valid topology:

{
  "resources": []
}

Topology with all fields:

{
  "resources": [ ... ],
  "connections": [ ... ],
  "groups": [ ... ]
}

[!NOTE] connections and groups are OPTIONAL. If omitted, they are treated as empty arrays. Producers MAY omit these fields entirely or provide them as empty arrays.

9.2.4 Resource required fields

Every resource object MUST contain:

Validation rules:

• V-RES-001: Resource MUST contain id, type and provider fields
• V-RES-002: Resource id MUST be a non-empty string
• V-RES-003: Resource id MUST be unique within the document
• V-RES-004: Resource type MUST be a non-empty string
• V-RES-005: Resource type MUST match format: ^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$
• V-RES-006: Resource type MUST contain at least two segments (e.g. compute.vm, not just compute)
• V-RES-007: Resource provider MUST be an object

9.2.4.1 Provider required fields

The provider object within a resource MUST contain:

Validation rules:

• V-PROV-001: Provider object MUST contain name field
• V-PROV-002: Provider name MUST be a non-empty string
• V-PROV-003: Provider name MUST match format: ^[a-z0-9]+(\.[a-z0-9]+)*$ (lowercase letters, digits, dots only)
• V-PROV-004: Provider name SHOULD be a well-known canonical name (aws, azure, gcp, vmware, dell, cisco, arista, etc.)

Valid provider objects:

{ "name": "aws" }
{ "name": "azure" }
{ "name": "dell" }
{ "name": "cisco.aci" }  // Multi-segment allowed

Invalid provider objects:

{ "name": "AWS" }           // Not lowercase
{ "name": "amazon-aws" }    // Contains hyphen
{ "name": "" }              // Empty string
{ }                         // Missing name field

Recommended fields (OPTIONAL):

• type (string): Vendor-specific resource type (e.g. "AWS::EC2::Instance", "PowerEdge R770")
• native_id (string): Vendor’s native identifier (e.g. "i-0abc123")
• region (string): Geographic region or zone
• account (string): Account, subscription or project ID

9.2.5 Connection required fields

Every connection object MUST contain:

Validation rules:

• V-CONN-001: Connection MUST contain id, source, target and type fields
• V-CONN-002: Connection id MUST be a non-empty string
• V-CONN-003: Connection id MUST be unique within the document
• V-CONN-004: Connection source MUST reference a valid resource id
• V-CONN-005: Connection target MUST reference a valid resource id
• V-CONN-006: Connection type MUST be a non-empty string
• V-CONN-007: Connection type MUST match format: ^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$

Valid connection:

{
  "id": "conn-web-to-db",
  "source": "aws::i-0abc123",
  "target": "aws::db-prod-01",
  "type": "dependency"
}

Invalid connections:

// Missing required type field
{
  "id": "conn-001",
  "source": "aws::i-0abc123",
  "target": "aws::db-prod-01"
}

// Invalid type format
{
  "id": "conn-001",
  "source": "aws::i-0abc123",
  "target": "aws::db-prod-01",
  "type": "TCP_CONNECTION"  // Uppercase, underscore
}

// Dangling reference
{
  "id": "conn-001",
  "source": "aws::i-0abc123",
  "target": "nonexistent-resource",  // Not in resources array
  "type": "dependency"
}

9.2.6 Group required fields

Every group object MUST contain:

Validation rules:

• V-GRP-001: Group MUST contain id and type fields
• V-GRP-002: Group id MUST be a non-empty string
• V-GRP-003: Group id MUST be unique within the document
• V-GRP-004: Group type MUST be a non-empty string
• V-GRP-005: Group type MUST match format: ^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$
• V-GRP-006: If present, group members MUST be an array of strings
• V-GRP-007: If present, each group members entry MUST reference a valid resource id
• V-GRP-008: If present, group children MUST be an array of strings
• V-GRP-009: If present, each group children entry MUST reference a valid group id

Valid group:

{
  "id": "grp-production-vpc",
  "type": "network.vpc",
  "members": [
    "aws::i-0abc123",
    "aws::i-0def456"
  ]
}

Invalid groups:

// Missing type
{
  "id": "grp-001",
  "members": [ "aws::i-0abc123" ]
}

// Invalid type format
{
  "id": "grp-001",
  "type": "Production_VPC",  // Uppercase, underscore
  "members": [ "aws::i-0abc123" ]
}

// Dangling member reference
{
  "id": "grp-001",
  "type": "network.vpc",
  "members": [
    "aws::i-0abc123",
    "nonexistent-resource"  // Not in resources array
  ]
}

9.3 Validation rules

Beyond structural requirements enforced by JSON Schema, OSIRIS defines semantic and domain validation rules. These rules address referential integrity, naming conventions, type validity and extension usage.

9.3.1 Validation levels

OSIRIS defines three validation levels that consumers MAY implement based on their requirements:

Level 1: Structural validation (REQUIRED)

What it validates:

• JSON syntax is correct
• Required fields are present
• Field types are correct (string, object, array, etc.)
• Field values match format patterns

Implementation: JSON Schema validation (Appendix A) Outcome: Document is syntactically valid Consumers MUST implement: Level 1 validation is mandatory

Level 2: Semantic validation (RECOMMENDED)

What it validates:

• ID uniqueness within document
• Referential integrity (connections > resources, groups > resources)
• Type format compliance (lowercase, dots only)
• Provider naming conventions
• Extension namespace format

Implementation: Custom validator logic after JSON Schema validation Outcome: Document is semantically valid and internally consistent Consumers SHOULD implement: Level 2 validation catches common producer errors

Level 3: Domain validation (OPTIONAL)

What it validates:

• Resource types are recognized (standard types from Chapter 7)
• Connection types are appropriate for resource types
• Properties follow conventions for resource types
• Extension namespaces are known/registered

Implementation: Domain-aware validator with knowledge of OSIRIS taxonomy Outcome: Document uses well-known types and follows conventions Consumers MAY implement: Level 3 validation provides additional quality checks but is not required for conformance

9.3.2 Identity validation rules

Rule category: Semantic (Level 2)

These rules ensure that identifiers are unique and well-formed:

V-ID-001: Resource ID uniqueness

• Rule: Every resource id MUST be unique within the document
• Level: Error
• Example violation:

  "resources": [
    { "id": "aws::i-0abc123", "type": "compute.vm", ... },
    { "id": "aws::i-0abc123", "type": "storage.volume", ... }  // Duplicate
  ]

V-ID-002: Connection ID uniqueness

• Rule: Every connection id MUST be unique within the document
• Level: Error
• Example violation:

  "connections": [
    { "id": "conn-001", ... },
    { "id": "conn-001", ... }  // Duplicate
  ]

V-ID-003: Group ID uniqueness

• Rule: Every group id MUST be unique within the document
• Level: Error
• Example violation:

  "groups": [
    { "id": "grp-prod", "type": "administrative", ... },
    { "id": "grp-prod", "type": "network.vpc", ... }  // Duplicate
  ]

V-ID-004: Non-empty IDs

• Rule: Resource, connection and group IDs MUST be non-empty strings
• Level: Error
• Example violation:

  { "id": "", "type": "compute.vm", ... }  // Empty ID

V-ID-005: Resource ID format recommendation

• Rule: Resource IDs SHOULD use provider::native-id format when applicable
• Level: Warning
• Example recommendation:

  // Recommended
  { "id": "aws::i-0abc123", ... }
  
  // Not recommended but valid
  { "id": "my-web-server", ... }

V-ID-006: Cross-scope uniqueness

• Rule: Resource, connection and group IDs occupy separate namespaces
• Guidance: Same ID string MAY be used for a resource, connection and group without conflict
• Example (valid):

  "resources": [ { "id": "vpc-001", ... } ],
  "groups": [ { "id": "vpc-001", ... } ]  // Valid (different namespaces)

9.3.3 Referential integrity rules

Rule category: Semantic (Level 2)

These rules ensure that ID references resolve correctly:

V-REF-001: Connection source validity

• Rule: Connection source MUST reference an existing resource id
• Level: Error
• Example violation:

  "resources": [
    { "id": "aws::i-0abc123", ... }
  ],
  "connections": [
    { "source": "aws::i-0def456", ... }  // Resource doesn't exist
  ]

V-REF-002: Connection target validity

• Rule: Connection target MUST reference an existing resource id
• Level: Error
• Example violation:

  "resources": [
    { "id": "aws::i-0abc123", ... }
  ],
  "connections": [
    { "target": "aws::db-nonexistent", ... }  // Resource doesn't exist
  ]

V-REF-003: Group member validity

• Rule: Each group members entry MUST reference an existing resource id
• Level: Error
• Example violation:

  "resources": [
    { "id": "aws::i-0abc123", ... }
  ],
  "groups": [
    {
      "members": [
        "aws::i-0abc123",
        "aws::i-0nonexistent"  // Resource doesn't exist
      ]
    }
  ]

V-REF-004: Group children validity

• Rule: Each group children entry MUST reference an existing group id
• Level: Error
• Example violation:

  "groups": [
    { "id": "grp-parent", "children": ["grp-child"] },
    // grp-child doesn't exist
  ]

V-REF-005: Circular group nesting

• Rule: Group hierarchies MUST NOT contain cycles
• Level: Error
• Example violation:

  "groups": [
    { "id": "grp-a", "children": ["grp-b"] },
    { "id": "grp-b", "children": ["grp-a"] }  // Circular reference
  ]

V-REF-006: Dangling references handling

• Rule: Consumers SHOULD report dangling references as warnings
• Guidance: Consumers MAY skip invalid connections/groups while processing valid resources
• Level: Warning (downgradeable from error for resilience)

9.3.4 Type format rules

Rule category: Structural (Level 1) and Semantic (Level 2)

These rules ensure type identifiers are well-formed:

V-TYPE-001: Type must be lowercase

• Rule: Type strings MUST contain only lowercase letters and digits
• Level: Error
• Example violations:

  "type": "Compute.VM"    // Uppercase
  "type": "compute.VM"    // Uppercase segment
  "type": "Compute"       // Uppercase

V-TYPE-002: Type must use dot separator

• Rule: Type segments MUST be separated by dots (.)
• Prohibition: Underscores (_), hyphens (-) and spaces are NOT ALLOWED in type strings
• Level: Error
• Example violations:

  "type": "compute_vm"    // Underscore
  "type": "compute-vm"    // Hyphen
  "type": "compute vm"    // Space

V-TYPE-003: Type must not start or end with dot

• Rule: Type strings MUST NOT start or end with a dot
• Level: Error
• Example violations:

  "type": ".compute.vm"   // Leading dot
  "type": "compute.vm."   // Trailing dot

V-TYPE-004: Type must not have consecutive dots

• Rule: Type strings MUST NOT contain consecutive dots (..)
• Level: Error
• Example violations:

  "type": "compute..vm"   // Consecutive dots
  "type": "compute...vm"  // Multiple consecutive dots

V-TYPE-005: Type must have minimum segments

• Rule: Type strings MUST contain at least two segments (category and subcategory)
• Level: Error
• Example violations:

  "type": "compute"       // Only one segment
  "type": "vm"            // Only one segment

V-TYPE-006: Type format pattern

• Rule: Type strings MUST match regex: ^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$
• Guidance: Start with lowercase letter, followed by lowercase letters/digits, then one or more dot-separated segments with same format
• Level: Error

V-TYPE-007: Custom type prefix

• Rule: Custom types MUST use osiris. prefix
• Guidance: Standard types MUST NOT use osiris. prefix
• Level: Error
• Example:

  // Standard type
  "type": "compute.vm"
  
  // Custom type
  "type": "osiris.aws.lambda.edge"
  
  // Standard type with osiris prefix
  "type": "osiris.compute.vm"

V-TYPE-008: Type depth recommendation

• Rule: Type strings SHOULD NOT exceed 4-5 segments
• Guidance: Highly specific details belong in properties, not type strings
• Level: Warning (informational, not error)

9.3.5 Provider validation rules

Rule category: Semantic (Level 2)

These rules ensure provider information is well-formed:

V-PROV-001: Provider name lowercase

• Rule: Provider name MUST be lowercase
• Level: Error
• Example violations:

  "provider": { "name": "AWS" }      // Uppercase
  "provider": { "name": "Azure" }    // Mixed case

V-PROV-002: Provider name format

• Rule: Provider name MUST match pattern: ^[a-z0-9]+(\.[a-z0-9]+)*$
• Allowed: Lowercase letters, digits, dots only
• Not allowed: Hyphens, underscores, spaces, uppercase
• Level: Error
• Example violations:

  "provider": { "name": "amazon-aws" }   // Hyphen
  "provider": { "name": "cisco_aci" }    // Underscore

V-PROV-003: Well-known provider names

• Rule: Producers SHOULD use canonical provider names for well-known vendors
• Canonical names: aws, azure, gcp, oci, vmware, proxmox, dell, hpe, cisco, arista, juniper, paloalto, fortinet, etc.
• Level: Warning
• Example recommendations:

  // Recommended
  "provider": { "name": "aws" }
  
  // Not recommended but valid
  "provider": { "name": "amazon" }
  "provider": { "name": "amazonwebservices" }

V-PROV-004: Provider field recommendations

• Rule: Provider objects SHOULD include type, native_id and region when applicable
• Level: Informational

9.3.6 Extension validation rules

Rule category: Semantic (Level 2) These rules ensure extensions follow the namespace conventions defined in Chapter 8:

V-EXT-001: Extension namespace prefix

• Rule: Extension fields MUST use osiris.<namespace> prefix
• Level: Error
• Example:

  // Valid
  "extensions": {
    "osiris.aws": { ... },
    "osiris.com.acme": { ... }
  }
  
  // Invalid (missing osiris prefix)
  "extensions": {
    "aws": { ... },
    "custom": { ... }
  }

V-EXT-002: Extension namespace format

• Rule: Extension namespaces MUST match pattern: ^osiris\.[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$
• Level: Error
• Example violations:

  "extensions": {
    "osiris.AWS": { ... },          // Uppercase
    "osiris.my-company": { ... },   // Hyphen
    "osiris.": { ... }               // Incomplete
  }

V-EXT-003: Unknown extensions

• Rule: Consumers MUST accept documents with unknown extension namespaces
• Guidance: Consumers MAY log warnings for unrecognized extensions but MUST NOT reject documents
• Level: Informational

V-EXT-004: Extension namespace registration

• Rule: Producers SHOULD document custom extension namespaces
• Guidance: Extension namespaces SHOULD use reverse domain notation for organization-specific extensions (e.g. osiris.com.acme)
• Level: Informational

9.3.7 Domain validation rules

Rule category: Domain (Level 3, OPTIONAL)

These rules validate against known types and conventions:

V-DOM-001: Known resource types

• Rule: Resource types SHOULD be standard types from Chapter 7
• Guidance: Consumers MAY warn about unrecognized types but MUST NOT reject documents
• Level: Warning (informational)

V-DOM-002: Known connection types

• Rule: Connection types SHOULD be standard types from Chapter 5
• Standard types: network, dependency, contains, dataflow, physical, plus protocol-specific subtypes
• Level: Warning (informational)

V-DOM-003: Known group types

• Rule: Group types SHOULD be standard types from Chapter 6
• Standard types: administrative, structural, plus category-specific subtypes
• Level: Warning (informational)

V-DOM-004: Property conventions

• Rule: Properties SHOULD follow naming conventions for resource types
• Example: compute.vm resources typically have vcpus, memory_gb, instance_type
• Level: Informational

V-DOM-005: Connection semantics

• Rule: Connections SHOULD make semantic sense for resource type pairs
• Example: dependency connections typically link application components
• Level: Informational

9.3.8 Validation error levels

OSIRIS defines three error severity levels:

ERROR (MUST Fix)

Severity: Critical - document is malformed

Action: Producers MUST fix errors before emission. Consumers MUST reject documents or emit clear error messages.

Examples:

• Missing required fields
• Invalid JSON syntax
• Duplicate IDs
• Dangling references
• Invalid type formats

Consumer behavior: Stop processing or provide diagnostic information only

WARNING (SHOULD Fix)

Severity: Important - document may have issues

Action: Producers SHOULD address warnings. Consumers SHOULD log warnings but MAY continue processing.

Examples:

• Non-standard provider names
• Missing recommended fields
• Unrecognized but valid types
• Non-recommended ID formats

Consumer behavior: Log warning, continue processing

INFO (MAY Fix)

Severity: Informational - potential improvements

Action: Producers MAY address informational issues. Consumers MAY log info messages.

Examples:

• Optional fields not present
• Property naming suggestions
• Type depth recommendations
• Extension namespace suggestions

Consumer behavior: Optional logging, continue processing

9.3.9 Validation implementation guidance

For producers

Validation workflow:

1. Generate OSIRIS document
2. Validate against JSON Schema (Level 1)
   • If fails: Fix errors and retry
3. Run semantic validation (Level 2)
   • If errors: Fix and retry
   • If warnings: Log and optionally fix
4. Optionally run domain validation (Level 3)
   • Log informational messages
5. Emit document

Best practices:

• Validate before emission (catch errors early)
• Log all warnings and errors during generation
• Provide clear error messages with context
• Test validator with invalid documents
• Include validation in CI/CD pipelines

For consumers

Validation workflow:

1. Receive OSIRIS document
2. Validate against JSON Schema (Level 1)
   • If fails: Reject document with error message
3. Run semantic validation (Level 2)
   • If errors: Reject or warn user
   • If warnings: Log warnings
4. Optionally run domain validation (Level 3)
   • Log informational messages
5. Process document

Best practices:

• Always perform Level 1 (structural) validation
• Implement Level 2 (semantic) validation for production systems
• Provide clear, actionable error messages
• Allow users to configure validation strictness
• Log validation events for debugging
• Handle partial failures gracefully (e.g. skip invalid connections, process valid resources)

Validation libraries

Reference implementations: Producers and consumers SHOULD use or provide validation libraries that implement:

• JSON Schema validation (Level 1)
• Semantic rule checking (Level 2)
• Optional domain validation (Level 3)

9.4 Validation examples

9.4.1 Valid minimal document

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": {
    "timestamp": "2026-01-01T18:30:00Z",
    "generator": {
      "name": "",
      "version": ""
    }
  },
  "topology": {
    "resources": []
  }
}

Validation result:

• Level 1: PASS (structure valid)
• Level 2: PASS (no semantic issues)
• Level 3: PASS (no domain issues)

9.4.2 Valid document with resources and connections

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": {
    "timestamp": "2026-01-01T18:30:00Z",
    "generator": {
      "name": "osiris-aws-parser",
      "version": "1.0.0"
    }
  },
  "topology": {
    "resources": [
      {
        "id": "aws::i-0abc123",
        "type": "compute.vm",
        "provider": {
          "name": "aws",
          "type": "AWS::EC2::Instance",
          "native_id": "i-0abc123",
          "region": "us-east-1",
          "account": "123456789012"
        }
      },
      {
        "id": "aws::db-prod-01",
        "type": "application.database",
        "provider": {
          "name": "aws",
          "type": "AWS::RDS::DBInstance",
          "native_id": "db-prod-01",
          "region": "us-east-1",
          "account": "123456789012"
        }
      }
    ],
    "connections": [
      {
        "id": "conn-web-to-db",
        "source": "aws::i-0abc123",
        "target": "aws::db-prod-01",
        "type": "dependency",
        "direction": "forward"
      }
    ]
  }
}

Validation result:

• Level 1: PASS (structure valid)
• Level 2: PASS (IDs unique, references valid)
• Level 3: PASS (standard types used)

9.4.3 Invalid document (missing required field)

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": {
    "timestamp": "2026-01-02T10:35:00Z",
    "generator": {
      "name": "osiris-aws-parser",
      "version": "1.0.0"
    }
  },
  "topology": {
    "resources": [
      {
        "id": "aws::i-0abc123",
        "type": "compute.vm"
        // Missing required "provider" field
      }
    ]
  }
}

Validation result:

• Level 1: FAIL
  • Error V-RES-001: Resource missing required field ‘provider’
  • Location: topology.resources[0]

9.4.4 Invalid document (dangling reference)

{
  "version": "1.0.0",
  "metadata": {
    "timestamp": "2026-01-02T10:35:00Z",
    "generator": {
      "name": "osiris-aws-parser",
      "version": "1.0.0"
    }
  },
  "topology": {
    "resources": [
      {
        "id": "aws::i-0abc123",
        "type": "compute.vm",
        "provider": { "name": "aws" }
      }
    ],
    "connections": [
      {
        "id": "conn-001",
        "source": "aws::i-0abc123",
        "target": "aws::db-nonexistent",  // Resource doesn't exist, ID doesn't match
        "type": "dependency"
      }
    ]
  }
}

Validation result:

• Level 1: PASS (structure valid)
• Level 2: FAIL
  • Error V-REF-002: Connection target references non-existent resource ‘aws::db-nonexistent’
  • Location: topology.connections[0].target

9.4.5 Invalid document (invalid type format)

{
  "version": "1.0.0",
  "metadata": {
    "timestamp": "2026-01-02T10:55:00Z",
    "generator": {
      "name": "osiris-aws-parser",
      "version": "1.0.0"
    }
  },
  "topology": {
    "resources": [
      {
        "id": "aws::i-0abc123",
        "type": "Compute_VM",  // Uppercase and underscore
        "provider": { "name": "aws" }
      }
    ]
  }
}

Validation result:

• Level 1: FAIL
  • Error V-TYPE-001: Type must be lowercase (found: ‘Compute_VM’)
  • Error V-TYPE-002: Type must use dot separator, not underscore
  • Location: topology.resources[0].type

9.5 Summary

OSIRIS validation operates at three levels:

1. Structural (Level 1) REQUIRED: JSON Schema validation
2. Semantic (Level 2) RECOMMENDED: Referential integrity and naming rules
3. Domain (Level 3) OPTIONAL: Type recognition and conventions

Key validation rules:

• Required fields must be present (document, metadata, topology, resources, connections, groups)
• IDs must be unique within their scope (resources, connections, groups)
• References must resolve (connections > resources, groups > resources)
• Types must use lowercase dot notation (e.g. compute.vm, not Compute_VM)
• Provider names must be lowercase (e.g. aws, not AWS)
• Extensions must use osiris.* namespace prefix

Validation workflow:

1. Producers MUST validate before emission and fix errors before publishing
2. Consumers MUST validate on receipt and reject or flag invalid documents (per their policy)
3. Unknown extensions MUST be accepted (forward compatibility)

Implementation guidance:

• Use JSON Schema for Level 1 validation
• Implement custom validation logic for Level 2
• Optionally implement domain awareness for Level 3
• Provide clear error messages with location information
• Log warnings without failing validation
• Allow configuration of validation strictness

The validation rules defined in this chapter ensure that OSIRIS documents are well-formed, internally consistent and interoperable across implementations while maintaining forward compatibility for ecosystem evolution.