diff --git a/schemas/jsonschema/dcm-common.json b/schemas/jsonschema/dcm-common.json new file mode 100644 index 0000000..d6277b0 --- /dev/null +++ b/schemas/jsonschema/dcm-common.json @@ -0,0 +1,437 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://dcm-project.io/schemas/common/v1", + "title": "DCM Common Types", + "description": "Shared primitive and composite types reused across all DCM schemas.", + "$defs": { + "uuid": { + "type": "string", + "format": "uuid", + "description": "RFC 4122 UUID v4" + }, + "handle": { + "type": "string", + "pattern": "^[a-z0-9][a-z0-9-_/]*[a-z0-9]$", + "minLength": 3, + "maxLength": 256, + "description": "Human-readable stable identifier. Format: //. Lowercase, hyphens, underscores, and slashes only." + }, + "semver": { + "type": "string", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "description": "Semantic version string (MAJOR.MINOR.PATCH[-prerelease][+build])" + }, + "iso8601_datetime": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 datetime with timezone (e.g., 2026-03-29T14:30:00Z)" + }, + "iso8601_duration": { + "type": "string", + "pattern": "^P(?:\\d+Y)?(?:\\d+M)?(?:\\d+W)?(?:\\d+D)?(?:T(?:\\d+H)?(?:\\d+M)?(?:\\d+S)?)?$", + "description": "ISO 8601 duration (e.g., P90D, PT24H, P1Y6M)" + }, + "resource_type_fqn": { + "type": "string", + "pattern": "^[A-Z][a-zA-Z0-9]+\\.[A-Z][a-zA-Z0-9]+$", + "description": "Fully-qualified resource type name. Format: . (e.g., Compute.VirtualMachine, Network.VLAN)" + }, + "data_classification": { + "type": "string", + "enum": [ + "public", + "internal", + "confidential", + "restricted", + "phi", + "pci", + "sovereign", + "classified" + ], + "description": "Data classification level. Ordered: public < internal < confidential < restricted < phi | pci < sovereign < classified. Note: phi, sovereign, and classified are immutable once set (ACC-003)." + }, + "deployment_posture": { + "type": "string", + "enum": [ + "minimal", + "dev", + "standard", + "prod", + "fsi", + "sovereign" + ], + "description": "DCM deployment profile posture" + }, + "lifecycle_status": { + "type": "string", + "enum": [ + "developing", + "proposed", + "active", + "deprecated", + "retired" + ], + "description": "Artifact lifecycle status" + }, + "country_code": { + "type": "string", + "pattern": "^[A-Z]{2}$", + "description": "ISO 3166-1 alpha-2 country code" + }, + "actor_ref": { + "type": "object", + "required": [ + "actor_uuid", + "actor_type" + ], + "additionalProperties": false, + "properties": { + "actor_uuid": { + "$ref": "#/$defs/uuid" + }, + "actor_type": { + "type": "string", + "enum": [ + "human", + "system_component", + "policy", + "provider", + "scheduled_job" + ] + }, + "display_name": { + "type": "string", + "maxLength": 256 + } + } + }, + "artifact_metadata": { + "type": "object", + "description": "Standard metadata present on every DCM Data artifact.", + "required": [ + "uuid", + "handle", + "version", + "status", + "created_at", + "updated_at", + "created_by" + ], + "additionalProperties": false, + "properties": { + "uuid": { + "$ref": "#/$defs/uuid" + }, + "handle": { + "$ref": "#/$defs/handle" + }, + "version": { + "$ref": "#/$defs/semver" + }, + "status": { + "$ref": "#/$defs/lifecycle_status" + }, + "created_at": { + "$ref": "#/$defs/iso8601_datetime" + }, + "updated_at": { + "$ref": "#/$defs/iso8601_datetime" + }, + "created_by": { + "$ref": "#/$defs/actor_ref" + }, + "created_via": { + "type": "string", + "enum": [ + "pr", + "api", + "migration", + "system" + ] + }, + "owned_by": { + "type": "object", + "required": [ + "display_name" + ], + "additionalProperties": false, + "properties": { + "display_name": { + "type": "string", + "maxLength": 256 + }, + "email": { + "type": "string", + "format": "email" + } + } + }, + "tags": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Arbitrary key-value tags for search and organisation" + } + } + }, + "field_provenance": { + "type": "object", + "description": "Field-level provenance metadata. Every data field on a DCM artifact may carry this as a sibling _provenance key.", + "required": [ + "source_type", + "recorded_at" + ], + "additionalProperties": false, + "properties": { + "source_type": { + "type": "string", + "enum": [ + "layer", + "consumer_input", + "policy_transformation", + "provider_reported", + "information_provider", + "system_default", + "operator_override" + ] + }, + "source_ref": { + "$ref": "#/$defs/uuid", + "description": "UUID of the source layer, policy, or provider that set this value" + }, + "recorded_at": { + "$ref": "#/$defs/iso8601_datetime" + }, + "recorded_by": { + "$ref": "#/$defs/actor_ref" + }, + "basis": { + "type": "string", + "maxLength": 512, + "description": "Human-readable rationale for this value" + }, + "confidence_score": { + "type": "number", + "minimum": 0, + "maximum": 1, + "description": "Confidence band for information-provider-sourced values (0.0\u20131.0)" + }, + "overridable": { + "type": "boolean", + "default": true + } + } + }, + "sovereignty_declaration": { + "type": "object", + "required": [ + "operating_jurisdictions", + "data_residency_zones" + ], + "additionalProperties": false, + "properties": { + "operating_jurisdictions": { + "type": "array", + "items": { + "$ref": "#/$defs/country_code" + }, + "minItems": 1 + }, + "data_residency_zones": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "description": "Zone IDs where data physically resides" + }, + "regulatory_frameworks": { + "type": "array", + "items": { + "type": "string" + }, + "description": "e.g., GDPR, HIPAA, FedRAMP" + }, + "sub_processors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "jurisdictions" + ], + "properties": { + "name": { + "type": "string" + }, + "jurisdictions": { + "type": "array", + "items": { + "$ref": "#/$defs/country_code" + } + }, + "purpose": { + "type": "string" + } + } + }, + "description": "Third parties with access to data handled by this provider" + }, + "inter_zone_agreements": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Legal frameworks governing cross-zone data transfers (e.g., EU-US DPF)" + } + } + }, + "accreditation_ref": { + "type": "object", + "required": [ + "accreditation_uuid", + "framework", + "status" + ], + "additionalProperties": false, + "properties": { + "accreditation_uuid": { + "$ref": "#/$defs/uuid" + }, + "framework": { + "type": "string", + "description": "e.g., iso_27001, soc2_type2, fedramp_moderate, hipaa_baa, pci_dss" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "active", + "expired", + "revoked" + ] + }, + "valid_until": { + "$ref": "#/$defs/iso8601_datetime" + }, + "certificate_ref": { + "type": "string", + "format": "uri" + } + } + }, + "pagination": { + "type": "object", + "description": "Standard pagination envelope for list responses", + "required": [ + "items", + "pagination" + ], + "properties": { + "items": { + "type": "array" + }, + "pagination": { + "type": "object", + "required": [ + "total", + "limit", + "offset" + ], + "additionalProperties": false, + "properties": { + "total": { + "type": "integer", + "minimum": 0 + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000 + }, + "offset": { + "type": "integer", + "minimum": 0 + }, + "next_cursor": { + "type": "string" + }, + "prev_cursor": { + "type": "string" + } + } + } + } + }, + "error_response": { + "type": "object", + "required": [ + "error" + ], + "additionalProperties": false, + "properties": { + "error": { + "type": "object", + "required": [ + "code", + "message", + "request_id" + ], + "additionalProperties": false, + "properties": { + "code": { + "type": "string", + "description": "Machine-readable error code (e.g., RESOURCE_NOT_FOUND, POLICY_DENIED)" + }, + "message": { + "type": "string", + "description": "Human-readable error description" + }, + "request_id": { + "$ref": "#/$defs/uuid", + "description": "Correlation ID for this request; present in all audit records" + }, + "rule_uuid": { + "$ref": "#/$defs/uuid", + "description": "UUID of the governing policy rule (present when code is POLICY_DENIED or GOVERNANCE_DENIED)" + }, + "fields": { + "type": "array", + "items": { + "type": "object", + "required": [ + "field", + "issue" + ], + "properties": { + "field": { + "type": "string" + }, + "issue": { + "type": "string" + } + } + }, + "description": "Field-level validation errors (present on 422)" + } + } + } + } + }, + "resource_type_ref": { + "description": "Resource type reference \u2014 accepts either a Fully Qualified Name (e.g., 'Compute.VirtualMachine') or a Resource Type Registry UUID. DCM resolves either form to the canonical resource_type_uuid + resource_type_name pair during request assembly. FQN is recommended for consumer-facing usage as it is stable across deployments. UUID is accepted for programmatic use where the UUID is obtained from the catalog.", + "oneOf": [ + { + "$ref": "#/$defs/resource_type_fqn", + "description": "FQN form: 'Category.TypeName' (e.g., 'Compute.VirtualMachine')" + }, + { + "type": "string", + "format": "uuid", + "description": "UUID form: Resource Type Registry UUID from the service catalog" + } + ] + } + } +} \ No newline at end of file diff --git a/schemas/jsonschema/dcm-entities.json b/schemas/jsonschema/dcm-entities.json new file mode 100644 index 0000000..8429f58 --- /dev/null +++ b/schemas/jsonschema/dcm-entities.json @@ -0,0 +1,414 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://dcm-project.io/schemas/entities/v1", + "title": "DCM Entity Schemas", + "description": "JSON Schema definitions for all three DCM entity types: Infrastructure Resource, Composite Resource, and Process Resource. See data-model/01-entity-types.md.", + + "$defs": { + + "entity_lifecycle_state": { + "type": "string", + "enum": [ + "REQUESTED", + "PENDING", + "PROVISIONING", + "REALIZED", + "OPERATIONAL", + "DEGRADED", + "MAINTENANCE", + "SUSPENDED", + "DECOMMISSIONING", + "DECOMMISSIONED", + "FAILED", + "PENDING_REVIEW", + "TIMEOUT_PENDING", + "LATE_REALIZATION_PENDING", + "INDETERMINATE_REALIZATION", + "COMPENSATION_IN_PROGRESS", + "COMPENSATION_FAILED", + "PENDING_EXPIRY_ACTION", + "INGESTED", + "ENRICHING", + "PROMOTED" + ], + "description": "Lifecycle state for Infrastructure Resource and Composite Resource entities. DECOMMISSIONED is the only terminal state for infrastructure resources; FAILED is terminal for process resources. PENDING_REVIEW requires human resolution. TIMEOUT_PENDING through COMPENSATION_FAILED are recovery states (Section 49.8). INGESTED through PROMOTED are ingestion states (Section 20.2)." + }, + + "process_lifecycle_state": { + "type": "string", + "enum": ["REQUESTED", "INITIATED", "EXECUTING", "COMPLETED", "FAILED", "CANCELLED"], + "description": "Lifecycle state for Process Resource entities. COMPLETED, FAILED, and CANCELLED are terminal. No SUSPENDED or PENDING_REVIEW states." + }, + + "ownership_model": { + "type": "string", + "enum": ["whole_allocation", "allocation", "shareable"], + "description": "whole_allocation: consumer owns entity outright. allocation: entity carved from a pool owned by another Tenant. shareable: consumer holds a stake; resource owner retains ownership." + }, + + "on_expiry_action": { + "type": "string", + "enum": ["decommission", "suspend", "notify", "escalate"] + }, + + "drift_status": { + "type": "string", + "enum": ["clean", "drifted", "unknown"] + }, + + "drift_severity": { + "type": "string", + "enum": ["minor", "significant", "critical"] + }, + + "billing_state": { + "type": "string", + "enum": ["billable", "non_billable", "reduced_rate"] + }, + + "composition_visibility": { + "type": "string", + "enum": ["opaque", "transparent", "selective"], + "description": "opaque: consumers see composite only. transparent: consumers see composite and all constituents. selective: policy declares which constituents are visible." + }, + + "composite_health": { + "type": "string", + "enum": ["healthy", "degraded", "failed"] + }, + + "constituent_role": { + "type": "string", + "enum": ["primary", "supporting", "optional"] + }, + + "rehydration_constraints": { + "type": "object", + "additionalProperties": false, + "properties": { + "min_auth_level": { + "type": "string", + "description": "Minimum authority tier name required to authorize rehydration" + }, + "allow_delegated_rehydration": { + "type": "boolean", + "default": false, + "description": "Whether a Tenant admin (not the original requester) may authorize rehydration" + } + } + }, + + "rehydration_history_entry": { + "type": "object", + "required": ["rehydrated_at", "previous_provider_uuid", "new_provider_uuid", "authorized_by"], + "additionalProperties": false, + "properties": { + "rehydration_uuid": { "$ref": "dcm-common.json#/$defs/uuid" }, + "rehydrated_at": { "$ref": "dcm-common.json#/$defs/iso8601_datetime" }, + "previous_provider_uuid": { "$ref": "dcm-common.json#/$defs/uuid" }, + "new_provider_uuid": { "$ref": "dcm-common.json#/$defs/uuid" }, + "authorized_by": { "$ref": "dcm-common.json#/$defs/actor_ref" }, + "reason": { "type": "string" } + } + }, + + "pending_review_record": { + "type": "object", + "required": ["trigger", "detected_at", "resolution_options"], + "additionalProperties": false, + "properties": { + "trigger": { + "type": "string", + "enum": [ + "rehydration_sovereignty_conflict", + "cross_tenant_authorization_revoked", + "ownership_transfer_conflict" + ] + }, + "detected_at": { "$ref": "dcm-common.json#/$defs/iso8601_datetime" }, + "conflict_detail": { "type": "string" }, + "resolution_options": { + "type": "array", + "items": { + "type": "string", + "enum": ["re_authorize", "release", "escalate", "manual_override"] + } + } + } + }, + + "relationship": { + "type": "object", + "required": ["relationship_uuid", "relationship_type", "target_entity_uuid", "created_at"], + "additionalProperties": false, + "properties": { + "relationship_uuid": { "$ref": "dcm-common.json#/$defs/uuid" }, + "relationship_type": { + "type": "string", + "enum": [ + "requires", + "contains", + "references", + "peer", + "allocated_from", + "constituent_of", + "has_constituent" + ] + }, + "target_entity_uuid": { "$ref": "dcm-common.json#/$defs/uuid" }, + "target_entity_type": { "$ref": "dcm-common.json#/$defs/resource_type_fqn" }, + "created_at": { "$ref": "dcm-common.json#/$defs/iso8601_datetime" }, + "metadata": { "type": "object", "additionalProperties": true } + } + }, + + "infrastructure_resource_entity": { + "type": "object", + "title": "Infrastructure Resource Entity", + "description": "A realized physical or virtual infrastructure resource. Persists after provisioning. Owned by exactly one Tenant. Subject to drift detection and TTL management. See data-model/01-entity-types.md Section 2.1.", + "required": [ + "artifact_metadata", + "entity_type", + "resource_type", + "resource_type_spec_version", + "lifecycle_state", + "owned_by_tenant_uuid", + "created_by_actor_uuid", + "ownership_model" + ], + "additionalProperties": true, + "properties": { + + "artifact_metadata": { "$ref": "dcm-common.json#/$defs/artifact_metadata" }, + + "entity_type": { + "type": "string", + "const": "infrastructure_resource" + }, + + "resource_type": { "$ref": "dcm-common.json#/$defs/resource_type_fqn" }, + "resource_type_spec_version": { "$ref": "dcm-common.json#/$defs/semver" }, + "lifecycle_state": { "$ref": "#/$defs/entity_lifecycle_state" }, + + "owned_by_tenant_uuid": { "$ref": "dcm-common.json#/$defs/uuid" }, + "created_by_actor_uuid": { "$ref": "dcm-common.json#/$defs/uuid" }, + "ownership_model": { "$ref": "#/$defs/ownership_model" }, + + "allocated_from_pool_uuid": { + "oneOf": [{ "$ref": "dcm-common.json#/$defs/uuid" }, { "type": "null" }], + "description": "UUID of the pool entity this was carved from. Null unless ownership_model is 'allocation'." + }, + "allocation_ref_uuid": { + "oneOf": [{ "$ref": "dcm-common.json#/$defs/uuid" }, { "type": "null" }] + }, + "shared_resource_uuid": { + "oneOf": [{ "$ref": "dcm-common.json#/$defs/uuid" }, { "type": "null" }], + "description": "UUID of the shared resource this is a stake in. Null unless ownership_model is 'shareable'." + }, + + "provider_uuid": { + "oneOf": [{ "$ref": "dcm-common.json#/$defs/uuid" }, { "type": "null" }] + }, + "provider_entity_id": { + "oneOf": [{ "type": "string", "maxLength": 512 }, { "type": "null" }], + "description": "The provider's own identifier for this resource (e.g., 'vm-12345'). Separate from the DCM UUID." + }, + "provider_entity_id_history": { + "type": "array", + "items": { + "type": "object", + "required": ["provider_entity_id", "valid_from"], + "properties": { + "provider_entity_id": { "type": "string" }, + "valid_from": { "$ref": "dcm-common.json#/$defs/iso8601_datetime" }, + "valid_to": { "$ref": "dcm-common.json#/$defs/iso8601_datetime" } + } + } + }, + + "ttl": { + "oneOf": [{ "$ref": "dcm-common.json#/$defs/iso8601_duration" }, { "type": "null" }] + }, + "ttl_expires_at": { + "oneOf": [{ "$ref": "dcm-common.json#/$defs/iso8601_datetime" }, { "type": "null" }] + }, + "on_expiry": { "$ref": "#/$defs/on_expiry_action" }, + "billing_state": { "$ref": "#/$defs/billing_state" }, + + "rehydration_constraints": { "$ref": "#/$defs/rehydration_constraints" }, + "rehydration_history": { + "type": "array", + "items": { "$ref": "#/$defs/rehydration_history_entry" } + }, + + "last_discovered_at": { + "oneOf": [{ "$ref": "dcm-common.json#/$defs/iso8601_datetime" }, { "type": "null" }] + }, + "drift_status": { "$ref": "#/$defs/drift_status" }, + "last_drift_severity": { + "oneOf": [{ "$ref": "#/$defs/drift_severity" }, { "type": "null" }] + }, + + "pending_review_record": { + "oneOf": [{ "$ref": "#/$defs/pending_review_record" }, { "type": "null" }], + "description": "Present only when lifecycle_state is PENDING_REVIEW." + }, + + "relationships": { + "type": "array", + "items": { "$ref": "#/$defs/relationship" } + } + }, + "if": { + "properties": { "lifecycle_state": { "const": "PENDING_REVIEW" } } + }, + "then": { + "required": ["pending_review_record"], + "properties": { + "pending_review_record": { "not": { "type": "null" } } + } + } + }, + + "composite_resource_entity": { + "type": "object", + "title": "Composite Resource Entity", + "description": "Produced by a Composite Service registration aggregating multiple constituent Infrastructure Resource Entities into a higher-order service. The composite is a first-class entity with its own UUID. See data-model/01-entity-types.md Section 2.2 and data-model/30-composite-service-model.md.", + "required": [ + "artifact_metadata", + "entity_type", + "resource_type", + "resource_type_spec_version", + "lifecycle_state", + "owned_by_tenant_uuid", + "composition_visibility", + "constituents" + ], + "additionalProperties": true, + "properties": { + + "artifact_metadata": { "$ref": "dcm-common.json#/$defs/artifact_metadata" }, + + "entity_type": { + "type": "string", + "const": "composite_resource" + }, + + "resource_type": { "$ref": "dcm-common.json#/$defs/resource_type_fqn" }, + "resource_type_spec_version": { "$ref": "dcm-common.json#/$defs/semver" }, + "lifecycle_state": { "$ref": "#/$defs/entity_lifecycle_state" }, + "owned_by_tenant_uuid": { "$ref": "dcm-common.json#/$defs/uuid" }, + + "composition_visibility": { "$ref": "#/$defs/composition_visibility" }, + "composite_health": { "$ref": "#/$defs/composite_health" }, + + "constituents": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "required": ["constituent_entity_uuid", "role", "required_for_composite_operational"], + "additionalProperties": false, + "properties": { + "constituent_entity_uuid": { "$ref": "dcm-common.json#/$defs/uuid" }, + "role": { "$ref": "#/$defs/constituent_role" }, + "required_for_composite_operational": { "type": "boolean" }, + "constituent_lifecycle_state": { "$ref": "#/$defs/entity_lifecycle_state" } + } + } + }, + + "provider_uuid": { + "oneOf": [{ "$ref": "dcm-common.json#/$defs/uuid" }, { "type": "null" }], + "description": "The Service Provider that registered the Composite Service this composite was instantiated from." + }, + + "ttl": { "oneOf": [{ "$ref": "dcm-common.json#/$defs/iso8601_duration" }, { "type": "null" }] }, + "ttl_expires_at": { "oneOf": [{ "$ref": "dcm-common.json#/$defs/iso8601_datetime" }, { "type": "null" }] }, + "on_expiry": { "$ref": "#/$defs/on_expiry_action" }, + "billing_state": { "$ref": "#/$defs/billing_state" }, + + "relationships": { + "type": "array", + "items": { "$ref": "#/$defs/relationship" } + } + } + }, + + "process_resource_entity": { + "type": "object", + "title": "Process Resource Entity", + "description": "An ephemeral execution: automation job, playbook, pipeline, or workflow. Does not persist after reaching a terminal state. Must declare max_execution_time. See data-model/01-entity-types.md Section 2.3.", + "required": [ + "artifact_metadata", + "entity_type", + "resource_type", + "resource_type_spec_version", + "lifecycle_state", + "owned_by_tenant_uuid", + "created_by_actor_uuid", + "max_execution_time" + ], + "additionalProperties": true, + "properties": { + + "artifact_metadata": { "$ref": "dcm-common.json#/$defs/artifact_metadata" }, + + "entity_type": { + "type": "string", + "const": "process_resource" + }, + + "resource_type": { "$ref": "dcm-common.json#/$defs/resource_type_fqn" }, + "resource_type_spec_version": { "$ref": "dcm-common.json#/$defs/semver" }, + "lifecycle_state": { "$ref": "#/$defs/process_lifecycle_state" }, + "owned_by_tenant_uuid": { "$ref": "dcm-common.json#/$defs/uuid" }, + "created_by_actor_uuid": { "$ref": "dcm-common.json#/$defs/uuid" }, + + "max_execution_time": { "$ref": "dcm-common.json#/$defs/iso8601_duration" }, + "started_at": { "oneOf": [{ "$ref": "dcm-common.json#/$defs/iso8601_datetime" }, { "type": "null" }] }, + "completed_at": { "oneOf": [{ "$ref": "dcm-common.json#/$defs/iso8601_datetime" }, { "type": "null" }] }, + "execution_timeout_at": { "oneOf": [{ "$ref": "dcm-common.json#/$defs/iso8601_datetime" }, { "type": "null" }] }, + + "affected_entity_uuids": { + "type": "array", + "items": { "$ref": "dcm-common.json#/$defs/uuid" }, + "description": "UUIDs of all Infrastructure Resource Entities modified during this process. Mandatory if any modifications were made." + }, + + "provider_uuid": { "oneOf": [{ "$ref": "dcm-common.json#/$defs/uuid" }, { "type": "null" }] }, + "provider_job_id": { "oneOf": [{ "type": "string", "maxLength": 512 }, { "type": "null" }] }, + + "exit_status": { + "oneOf": [ + { "type": "string", "enum": ["success", "failure", "timeout", "cancelled"] }, + { "type": "null" } + ] + }, + "execution_log_ref": { + "oneOf": [{ "$ref": "dcm-common.json#/$defs/uuid" }, { "type": "null" }], + "description": "Reference to the log store entry for this process execution." + } + } + }, + + "dcm_entity": { + "oneOf": [ + { "$ref": "#/$defs/infrastructure_resource_entity" }, + { "$ref": "#/$defs/composite_resource_entity" }, + { "$ref": "#/$defs/process_resource_entity" } + ], + "discriminator": { + "propertyName": "entity_type", + "mapping": { + "infrastructure_resource": "#/$defs/infrastructure_resource_entity", + "composite_resource": "#/$defs/composite_resource_entity", + "process_resource": "#/$defs/process_resource_entity" + } + } + } + + }, + + "$ref": "#/$defs/dcm_entity" +} diff --git a/schemas/jsonschema/dcm-policies.json b/schemas/jsonschema/dcm-policies.json new file mode 100644 index 0000000..22d8d8a --- /dev/null +++ b/schemas/jsonschema/dcm-policies.json @@ -0,0 +1,652 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://dcm-project.io/schemas/policies/v1", + "title": "DCM Policy Schemas", + "description": "JSON Schema definitions for all seven DCM policy types and their output schemas. See data-model/B-policy-contract.md and data-model/14-policy-profiles.md.", + + "$defs": { + + "policy_type": { + "type": "string", + "enum": [ + "gatekeeper", + "validation", + "transformation", + "recovery", + "orchestration_flow", + "governance_matrix_rule", + "lifecycle", + "itsm_action" + ] + }, + + "concern_type": { + "type": "string", + "enum": [ + "security", + "compliance", + "operational", + "recovery_posture", + "zero_trust_posture", + "data_authorization_boundary", + "orchestration_flow" + ] + }, + + "policy_domain": { + "type": "string", + "enum": ["system", "platform", "tenant", "resource_type", "entity"] + }, + + "payload_type": { + "type": "string", + "enum": [ + "request.initiated", + "request.layers_assembled", + "request.policy_evaluated", + "request.placement_resolved", + "request.dispatched", + "resource.state_changed", + "resource.drift_detected", + "provider.registered", + "provider.health_changed", + "contribution.submitted", + "contribution.approved" + ], + "description": "Closed vocabulary of DCM pipeline events that policies can match against." + }, + + "match_condition": { + "type": "object", + "required": ["field", "operator"], + "additionalProperties": false, + "properties": { + "field": { + "type": "string", + "description": "Dot-notation path into the payload (e.g., request.resource_type, resource.lifecycle_state)" + }, + "operator": { + "type": "string", + "enum": ["equals", "not_equals", "in", "not_in", "minimum", "maximum", "contains", "matches"] + }, + "value": { + "description": "Comparison value. Type must match the referenced field." + } + } + }, + + "model_a_match": { + "type": "object", + "title": "Model A Match — Payload type and field conditions", + "description": "Used by pipeline policies: GateKeeper, Validation, Transformation, Recovery, Orchestration Flow.", + "required": ["payload_type"], + "additionalProperties": false, + "properties": { + "payload_type": { "$ref": "#/$defs/payload_type" }, + "conditions": { + "type": "array", + "items": { "$ref": "#/$defs/match_condition" } + }, + "condition_logic": { + "type": "string", + "enum": ["all", "any"], + "default": "all" + } + } + }, + + "subject_match": { + "type": "object", + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "enum": ["human_actor", "system_component", "provider", "peer_dcm"] + }, + "identity": { "type": "object", "additionalProperties": true }, + "tenant": { "type": "object", "additionalProperties": true } + } + }, + + "data_match": { + "type": "object", + "additionalProperties": false, + "properties": { + "classification": { "$ref": "dcm-common.json#/$defs/data_classification" }, + "resource_type": { "$ref": "dcm-common.json#/$defs/resource_type_fqn" }, + "field_paths": { + "type": "object", + "required": ["mode"], + "additionalProperties": false, + "properties": { + "mode": { "type": "string", "enum": ["allowlist", "blocklist"] }, + "paths": { "type": "array", "items": { "type": "string" } } + } + }, + "capability": { "type": "string" } + } + }, + + "target_match": { + "type": "object", + "additionalProperties": false, + "properties": { + "type": { "type": "string", "enum": ["provider", "peer_dcm", "data_store"] }, + "sovereignty_zone": { + "type": "object", + "properties": { + "match": { "type": "string", "description": "Zone ID or pattern" } + } + }, + "accreditation_held": { + "type": "object", + "properties": { + "includes": { "type": "array", "items": { "type": "string" } } + } + }, + "trust_posture": { "type": "string", "enum": ["verified", "vouched", "provisional"] } + } + }, + + "context_match": { + "type": "object", + "additionalProperties": false, + "properties": { + "profile": { + "type": "object", + "properties": { + "deployment_posture": { "$ref": "dcm-common.json#/$defs/deployment_posture" } + } + }, + "zero_trust_posture": { + "type": "object", + "properties": { + "minimum": { + "type": "string", + "enum": ["none", "boundary", "full", "hardware_attested"] + } + } + }, + "federated": { "type": "boolean" } + } + }, + + "model_b_match": { + "type": "object", + "title": "Model B Match — Four-axis boundary conditions", + "description": "Used by boundary policies: Governance Matrix Rules.", + "additionalProperties": false, + "properties": { + "subject": { "$ref": "#/$defs/subject_match" }, + "data": { "$ref": "#/$defs/data_match" }, + "target": { "$ref": "#/$defs/target_match" }, + "context": { "$ref": "#/$defs/context_match" } + } + }, + + "base_policy_artifact": { + "type": "object", + "description": "Fields common to all policy types.", + "required": [ + "artifact_metadata", + "policy_type", + "concern_type", + "domain", + "enforcement" + ], + "properties": { + "artifact_metadata": { "$ref": "dcm-common.json#/$defs/artifact_metadata" }, + "policy_type": { "$ref": "#/$defs/policy_type" }, + "concern_type": { "$ref": "#/$defs/concern_type" }, + "domain": { "$ref": "#/$defs/policy_domain" }, + "enforcement": { + "type": "string", + "enum": ["hard", "soft"], + "description": "hard: cannot be relaxed by any downstream rule. soft: downstream rules may tighten but not relax." + }, + "shadow_mode": { + "type": "boolean", + "default": false, + "description": "When true, policy evaluates but does not enforce. Results written to Validation Store only." + }, + "description": { "type": "string" }, + "rationale": { "type": "string", "description": "Why this policy exists; links to regulatory or operational requirement" } + } + }, + + "gatekeeper_output": { + "type": "object", + "title": "GateKeeper Output Schema", + "description": "Binary allow/deny decision. Compliance enforcement_class: always fail-safe (deny on error). Operational enforcement_class: contributes risk_score_contribution to aggregate score.", + "required": ["decision", "enforcement_class"], + "additionalProperties": false, + "properties": { + "decision": { + "type": "string", + "enum": ["allow", "deny"] + }, + "enforcement_class": { + "type": "string", + "enum": ["compliance", "operational"], + "description": "compliance: boolean deny, fail-safe, for regulatory mandates. operational: contributes weighted risk score." + }, + "risk_score_contribution": { + "type": "integer", + "minimum": 0, + "maximum": 100, + "description": "Required when enforcement_class is 'operational'. Weight contributed to aggregate risk score." + }, + "reason": { + "type": "string", + "description": "Human-readable reason for the decision. Required when decision is 'deny'." + }, + "rule_ref": { + "type": "string", + "description": "Reference to the specific rule within this policy that produced the decision." + } + }, + "if": { "properties": { "enforcement_class": { "const": "operational" } } }, + "then": { "required": ["risk_score_contribution"] } + }, + + "validation_output": { + "type": "object", + "title": "Validation Output Schema", + "description": "Field-level validation result. Pass/fail with field-specific detail.", + "required": ["result"], + "additionalProperties": false, + "properties": { + "result": { + "type": "string", + "enum": ["pass", "fail"] + }, + "field_results": { + "type": "array", + "items": { + "type": "object", + "required": ["field", "result"], + "additionalProperties": false, + "properties": { + "field": { "type": "string" }, + "result": { "type": "string", "enum": ["pass", "fail"] }, + "message": { "type": "string" }, + "value_received": { }, + "constraint_violated": { "type": "string" } + } + } + }, + "message": { "type": "string" } + } + }, + + "transformation_mutation": { + "type": "object", + "required": ["field", "operation"], + "additionalProperties": false, + "properties": { + "field": { "type": "string", "description": "Dot-notation field path to modify" }, + "operation": { + "type": "string", + "enum": ["set", "append", "remove", "redact", "default_if_absent"] + }, + "value": { "description": "New value for set/append/default_if_absent operations" }, + "provenance_basis": { + "type": "string", + "description": "Recorded as the provenance basis for the transformed field value" + } + } + }, + + "transformation_output": { + "type": "object", + "title": "Transformation Output Schema", + "description": "Data enrichment or mutation. Produces an ordered list of field mutations applied to the request payload.", + "required": ["mutations"], + "additionalProperties": false, + "properties": { + "mutations": { + "type": "array", + "minItems": 1, + "items": { "$ref": "#/$defs/transformation_mutation" } + }, + "description": { "type": "string" } + } + }, + + "recovery_output": { + "type": "object", + "title": "Recovery Output Schema", + "description": "Recovery action to take when a trigger condition is detected.", + "required": ["trigger", "action"], + "additionalProperties": false, + "properties": { + "trigger": { + "type": "string", + "enum": [ + "realization_failed", + "provider_timeout", + "provider_unavailable", + "drift_detected_critical", + "drift_detected_significant", + "accreditation_gap", + "sovereignty_conflict", + "dependency_failed", + "process_timeout", + "health_check_failed" + ], + "description": "Closed vocabulary of conditions that activate this recovery policy." + }, + "action": { + "type": "string", + "enum": [ + "retry", + "requeue", + "rehydrate", + "notify_and_wait", + "escalate", + "revert_to_requested", + "discard", + "alert_only" + ], + "description": "Closed vocabulary of recovery actions." + }, + "params": { + "type": "object", + "additionalProperties": true, + "description": "Action-specific parameters (e.g., max_retries, retry_interval, escalation_target)" + }, + "max_retries": { "type": "integer", "minimum": 0 }, + "retry_interval": { "$ref": "dcm-common.json#/$defs/iso8601_duration" }, + "timeout": { "$ref": "dcm-common.json#/$defs/iso8601_duration" } + } + }, + + "orchestration_step": { + "type": "object", + "required": ["step_id", "step_type"], + "additionalProperties": false, + "properties": { + "step_id": { "type": "string" }, + "step_type": { + "type": "string", + "enum": [ + "provider_dispatch", + "policy_evaluation", + "placement_resolution", + "layer_assembly", + "approval_gate", + "notification", + "dependency_wait", + "parallel_group" + ] + }, + "description": { "type": "string" }, + "depends_on": { + "type": "array", + "items": { "type": "string" }, + "description": "step_ids that must complete before this step executes" + }, + "params": { "type": "object", "additionalProperties": true }, + "on_failure": { "$ref": "#/$defs/recovery_output" } + } + }, + + "orchestration_flow_output": { + "type": "object", + "title": "Orchestration Flow Output Schema", + "description": "Named, ordered workflow. Declares the explicit step sequence for a request type. Evaluated by the Request Orchestrator.", + "required": ["flow_name", "ordered", "steps"], + "additionalProperties": false, + "properties": { + "flow_name": { "type": "string" }, + "ordered": { "type": "boolean", "const": true }, + "steps": { + "type": "array", + "minItems": 1, + "items": { "$ref": "#/$defs/orchestration_step" } + }, + "timeout": { "$ref": "dcm-common.json#/$defs/iso8601_duration" } + } + }, + + "governance_matrix_decision": { + "type": "string", + "enum": ["ALLOW", "DENY", "DENY_REQUEST", "STRIP_FIELD", "REDACT", "REQUIRE_APPROVAL"] + }, + + "governance_matrix_rule_output": { + "type": "object", + "title": "Governance Matrix Rule Output Schema", + "description": "Cross-boundary access control decision. Uses four-axis match (Model B). Produces an ALLOW/DENY/STRIP/REDACT decision. See data-model/27-governance-matrix.md.", + "required": ["decision"], + "additionalProperties": false, + "properties": { + "decision": { "$ref": "#/$defs/governance_matrix_decision" }, + "field_permissions": { + "type": "object", + "additionalProperties": false, + "description": "Per-field decisions when decision is STRIP_FIELD or REDACT.", + "properties": { + "mode": { "type": "string", "enum": ["allowlist", "blocklist"] }, + "fields": { + "type": "array", + "items": { + "type": "object", + "required": ["field_path", "action"], + "properties": { + "field_path": { "type": "string" }, + "action": { + "type": "string", + "enum": ["STRIP_FIELD", "REDACT", "DENY_REQUEST", "ALLOW"] + } + } + } + } + } + }, + "reason": { "type": "string" }, + "rule_ref": { "type": "string" } + } + }, + + "lifecycle_event_trigger": { + "type": "string", + "enum": [ + "entity.created", + "entity.state_changed", + "entity.relationship_added", + "entity.relationship_removed", + "entity.decommissioned", + "entity.ttl_expiring", + "entity.ownership_transferred" + ] + }, + + "lifecycle_policy_output": { + "type": "object", + "title": "Lifecycle Policy Output Schema", + "description": "Declarative rules governing entity lifecycle transitions and relationship events.", + "required": ["trigger", "action"], + "additionalProperties": false, + "properties": { + "trigger": { "$ref": "#/$defs/lifecycle_event_trigger" }, + "condition": { "type": "string", "description": "Optional condition expression on trigger payload" }, + "action": { + "type": "string", + "enum": [ + "notify", + "gate", + "cascade_decommission", + "release_relationship", + "escalate", + "enforce_retention" + ] + }, + "params": { "type": "object", "additionalProperties": true } + } + }, + + "gatekeeper_policy": { + "allOf": [ + { "$ref": "#/$defs/base_policy_artifact" }, + { + "type": "object", + "required": ["match", "output"], + "properties": { + "policy_type": { "const": "gatekeeper" }, + "match": { "$ref": "#/$defs/model_a_match" }, + "output": { "$ref": "#/$defs/gatekeeper_output" } + } + } + ] + }, + + "validation_policy": { + "allOf": [ + { "$ref": "#/$defs/base_policy_artifact" }, + { + "type": "object", + "required": ["match", "output"], + "properties": { + "policy_type": { "const": "validation" }, + "match": { "$ref": "#/$defs/model_a_match" }, + "output": { "$ref": "#/$defs/validation_output" } + } + } + ] + }, + + "transformation_policy": { + "allOf": [ + { "$ref": "#/$defs/base_policy_artifact" }, + { + "type": "object", + "required": ["match", "output"], + "properties": { + "policy_type": { "const": "transformation" }, + "match": { "$ref": "#/$defs/model_a_match" }, + "output": { "$ref": "#/$defs/transformation_output" } + } + } + ] + }, + + "recovery_policy": { + "allOf": [ + { "$ref": "#/$defs/base_policy_artifact" }, + { + "type": "object", + "required": ["match", "output"], + "properties": { + "policy_type": { "const": "recovery" }, + "match": { "$ref": "#/$defs/model_a_match" }, + "output": { "$ref": "#/$defs/recovery_output" } + } + } + ] + }, + + "orchestration_flow_policy": { + "allOf": [ + { "$ref": "#/$defs/base_policy_artifact" }, + { + "type": "object", + "required": ["match", "output"], + "properties": { + "policy_type": { "const": "orchestration_flow" }, + "match": { "$ref": "#/$defs/model_a_match" }, + "output": { "$ref": "#/$defs/orchestration_flow_output" } + } + } + ] + }, + + "governance_matrix_rule_policy": { + "allOf": [ + { "$ref": "#/$defs/base_policy_artifact" }, + { + "type": "object", + "required": ["match", "output"], + "properties": { + "policy_type": { "const": "governance_matrix_rule" }, + "match": { "$ref": "#/$defs/model_b_match" }, + "output": { "$ref": "#/$defs/governance_matrix_rule_output" } + } + } + ] + }, + + "lifecycle_policy": { + "allOf": [ + { "$ref": "#/$defs/base_policy_artifact" }, + { + "type": "object", + "required": ["output"], + "properties": { + "policy_type": { "const": "lifecycle" }, + "output": { "$ref": "#/$defs/lifecycle_policy_output" } + } + } + ] + }, + + "itsm_action_policy_output": { + "type": "object", + "description": "ITSM Action Policy output — side-effect policy that fires on DCM events and triggers ITSM actions. Non-blocking by default (ITSM-002). See data-model/42-itsm-integration.md.", + "required": ["itsm_provider_uuid", "action", "action_payload"], + "additionalProperties": false, + "properties": { + "itsm_provider_uuid": { "$ref": "dcm-common.json#/$defs/uuid" }, + "action": { "type": "string", "enum": ["create_change_request", "update_change_request", "close_change_request", "create_incident", "update_incident", "close_incident", "create_cmdb_ci", "update_cmdb_ci", "retire_cmdb_ci", "create_service_request"] }, + "action_payload": { "type": "object", "additionalProperties": true, "description": "Template payload — supports {{ field }} expressions resolved at evaluation time" }, + "store_reference_on_entity": { "type": "boolean", "default": true, "description": "Store ITSM record reference in entity business data (ITSM-004)" }, + "block_until_created": { "type": "boolean", "default": false, "description": "If true, block pipeline until ITSM record is created. Requires block_timeout (ITSM-005)." }, + "block_timeout": { "$ref": "dcm-common.json#/$defs/iso8601_duration", "description": "Required when block_until_created is true. Pipeline never permanently stalled." }, + "on_failure": { "type": "string", "enum": ["warn_and_continue", "fail_request"], "default": "warn_and_continue" } + } + }, + + "itsm_action_policy": { + "allOf": [ + { "$ref": "#/$defs/base_policy_artifact" }, + { + "type": "object", + "required": ["output"], + "properties": { + "policy_type": { "const": "itsm_action" }, + "output": { "$ref": "#/$defs/itsm_action_policy_output" } + } + } + ] + }, + + "dcm_policy": { + "oneOf": [ + { "$ref": "#/$defs/gatekeeper_policy" }, + { "$ref": "#/$defs/validation_policy" }, + { "$ref": "#/$defs/transformation_policy" }, + { "$ref": "#/$defs/recovery_policy" }, + { "$ref": "#/$defs/orchestration_flow_policy" }, + { "$ref": "#/$defs/governance_matrix_rule_policy" }, + { "$ref": "#/$defs/lifecycle_policy" }, + { "$ref": "#/$defs/itsm_action_policy" } + ], + "discriminator": { + "propertyName": "policy_type", + "mapping": { + "gatekeeper": "#/$defs/gatekeeper_policy", + "validation": "#/$defs/validation_policy", + "transformation": "#/$defs/transformation_policy", + "recovery": "#/$defs/recovery_policy", + "orchestration_flow": "#/$defs/orchestration_flow_policy", + "governance_matrix_rule":"#/$defs/governance_matrix_rule_policy", + "lifecycle": "#/$defs/lifecycle_policy", + "itsm_action": "#/$defs/itsm_action_policy" + } + } + } + + }, + + "$ref": "#/$defs/dcm_policy" +} diff --git a/schemas/jsonschema/dcm-providers.json b/schemas/jsonschema/dcm-providers.json new file mode 100644 index 0000000..d1bffa3 --- /dev/null +++ b/schemas/jsonschema/dcm-providers.json @@ -0,0 +1,513 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://dcm-project.io/schemas/providers/v1", + "title": "DCM Provider Schemas", + "description": "JSON Schema for DCM Provider registration and capability declarations. 5 provider types: service, information, auth, peer_dcm, process (composite services are a Data concept orchestrated by the Control Plane, not a provider type — see DCM-AI-PROMPT.md). Two policy evaluation modes: Internal (DCM evaluates via OPA) and External (external provider evaluates).", + "$defs": { + "provider_type": { + "type": "string", + "enum": [ + "service", + "information", + "auth", + "peer_dcm", + "process" + ], + "description": "DCM provider types. Service providers handle full resource lifecycle including credentials and notifications via resource_type declarations. Auth providers enable pluggable multi-IdP authentication with tenant routing. Process providers execute ephemeral workflows." + }, + "provider_status": { + "type": "string", + "enum": [ + "SUBMITTED", + "VALIDATING", + "PENDING_APPROVAL", + "ACTIVE", + "SUSPENDED", + "DEREGISTERING", + "DEREGISTERED", + "FORCED_DEREGISTERED" + ] + }, + "trust_posture": { + "type": "string", + "enum": [ + "verified", + "vouched", + "provisional" + ] + }, + "provider_health_response": { + "type": "object", + "required": [ + "status", + "version" + ], + "additionalProperties": false, + "properties": { + "status": { + "type": "string", + "enum": [ + "healthy", + "degraded", + "unhealthy" + ] + }, + "version": { + "type": "string" + }, + "capabilities_available": { + "type": "array", + "items": { + "type": "string" + } + }, + "details": { + "type": "object", + "additionalProperties": true, + "description": "Provider-specific detail. DCM treats as opaque." + } + } + }, + "certificate_declaration": { + "type": "object", + "required": [ + "pem", + "ca_chain", + "rotation_interval" + ], + "additionalProperties": false, + "properties": { + "pem": { + "type": "string", + "description": "PEM-encoded provider certificate" + }, + "ca_chain": { + "type": "string", + "description": "PEM-encoded CA chain" + }, + "rotation_interval": { + "$ref": "dcm-common.json#/$defs/iso8601_duration", + "description": "How frequently the provider rotates this certificate" + }, + "expires_at": { + "$ref": "dcm-common.json#/$defs/iso8601_datetime" + } + } + }, + "base_provider_registration": { + "type": "object", + "title": "Base Provider Registration", + "description": "Fields required in every provider registration regardless of type.", + "required": [ + "artifact_metadata", + "provider_type_id", + "display_name", + "sovereignty_declaration", + "health_endpoint", + "certificate", + "capability_extension" + ], + "properties": { + "artifact_metadata": { + "$ref": "dcm-common.json#/$defs/artifact_metadata" + }, + "provider_type_id": { + "$ref": "#/$defs/provider_type" + }, + "display_name": { + "type": "string", + "maxLength": 256 + }, + "description": { + "type": "string" + }, + "status": { + "$ref": "#/$defs/provider_status" + }, + "sovereignty_declaration": { + "$ref": "dcm-common.json#/$defs/sovereignty_declaration" + }, + "accreditations": { + "type": "array", + "items": { + "$ref": "dcm-common.json#/$defs/accreditation_ref" + } + }, + "health_endpoint": { + "type": "string", + "format": "uri" + }, + "health_poll_interval": { + "$ref": "dcm-common.json#/$defs/iso8601_duration", + "default": "PT5M" + }, + "failure_threshold": { + "type": "integer", + "minimum": 1, + "default": 3, + "description": "Consecutive failed health checks before status transitions to DEGRADED" + }, + "certificate": { + "$ref": "#/$defs/certificate_declaration" + }, + "trust_score": { + "type": "number", + "minimum": 0, + "maximum": 1, + "description": "DCM-computed trust score (0.0\u20131.0). Not set by provider; updated by DCM based on health, accreditation, and governance matrix checks." + }, + "capability_extension": { + "type": "object", + "description": "Provider-type-specific capability declaration. Schema determined by provider_type_id." + } + } + }, + "service_provider_capabilities": { + "type": "object", + "title": "Service Provider Capability Extension", + "description": "Capabilities for a Service Provider \u2014 realizes physical or virtual infrastructure resources.", + "required": [ + "offered_resource_types", + "services_endpoint" + ], + "additionalProperties": false, + "properties": { + "offered_resource_types": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "dcm-common.json#/$defs/resource_type_fqn" + }, + "description": "Resource types this provider can realize (e.g., Compute.VirtualMachine)" + }, + "services_endpoint": { + "type": "string", + "format": "uri" + }, + "discovery_endpoint": { + "type": "string", + "format": "uri" + }, + "reserve_query_endpoint": { + "type": "string", + "format": "uri" + }, + "max_concurrent_realizations": { + "type": "integer", + "minimum": 1 + }, + "realization_timeout_default": { + "$ref": "dcm-common.json#/$defs/iso8601_duration" + }, + "supports_suspension": { + "type": "boolean", + "default": false + }, + "supports_rehydration": { + "type": "boolean", + "default": false + }, + "cost_metadata": { + "type": "object", + "additionalProperties": true, + "description": "Provider-declared cost data consumed by the Cost Analysis component" + } + } + }, + "information_provider_capabilities": { + "type": "object", + "title": "Information Provider Capability Extension", + "required": [ + "authority_scope", + "interaction_model" + ], + "additionalProperties": false, + "properties": { + "authority_scope": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "description": "Field paths or resource type domains this provider has authority over (e.g., Network.VLAN.vlan_id)" + }, + "interaction_model": { + "type": "string", + "enum": [ + "push", + "pull", + "both" + ], + "description": "push: provider pushes updates to DCM. pull: DCM queries provider. both: supports either." + }, + "push_endpoint": { + "type": "string", + "format": "uri", + "description": "DCM endpoint where provider pushes updates (if interaction_model is push or both)" + }, + "pull_endpoint": { + "type": "string", + "format": "uri", + "description": "Provider endpoint DCM queries (if interaction_model is pull or both)" + }, + "write_back_endpoint": { + "type": "string", + "format": "uri", + "description": "Provider endpoint for DCM-initiated write-back operations" + }, + "schema_endpoint": { + "type": "string", + "format": "uri", + "description": "Where DCM retrieves the provider's extended field schema" + }, + "confidence_model": { + "type": "string", + "enum": [ + "declared", + "computed" + ], + "default": "declared" + }, + "max_staleness": { + "$ref": "dcm-common.json#/$defs/iso8601_duration" + } + } + }, + "composite_service_capabilities": { + "type": "object", + "title": "Composite Service Capability Extension", + "description": "Declares the catalog-level composite services this provider registers — multi-resource catalog items composed of declared constituent resource types. See data-model/30-composite-service-model.md.", + "required": [ + "offered_composite_types", + "constituent_providers" + ], + "additionalProperties": false, + "properties": { + "offered_composite_types": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "dcm-common.json#/$defs/resource_type_fqn" + } + }, + "constituent_providers": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "required": [ + "provider_uuid", + "role" + ], + "properties": { + "provider_uuid": { + "$ref": "dcm-common.json#/$defs/uuid" + }, + "role": { + "type": "string" + }, + "required": { + "type": "boolean", + "default": true + } + } + } + }, + "composition_endpoint": { + "type": "string", + "format": "uri" + }, + "compensation_strategy": { + "type": "string", + "enum": [ + "rollback_all", + "rollback_failed", + "notify_and_wait", + "best_effort" + ], + "description": "What to do if a constituent fails mid-composition" + }, + "composition_visibility": { + "type": "string", + "enum": [ + "opaque", + "transparent", + "selective" + ] + } + } + }, + "peer_dcm_capabilities": { + "type": "object", + "title": "Peer DCM Capability Extension", + "description": "Another DCM instance participating in a federation. Enables cross-instance request routing, audit correlation, and drift detection.", + "required": [ + "dcm_api_endpoint", + "trust_posture" + ], + "additionalProperties": false, + "properties": { + "dcm_api_endpoint": { + "type": "string", + "format": "uri" + }, + "federation_endpoint": { + "type": "string", + "format": "uri" + }, + "audit_endpoint": { + "type": "string", + "format": "uri" + }, + "trust_posture": { + "$ref": "#/$defs/trust_posture" + }, + "dcm_version": { + "$ref": "dcm-common.json#/$defs/semver" + }, + "federation_scope": { + "type": "string", + "enum": [ + "full", + "read_only", + "audit_only", + "resource_routing_only" + ], + "description": "What this peer DCM is authorized to do in the federation" + }, + "sovereignty_declaration": { + "$ref": "dcm-common.json#/$defs/sovereignty_declaration" + } + } + }, + "capability_extension": { + "description": "Provider-type-specific capability declaration. Schema determined by provider_type.", + "oneOf": [ + { + "$ref": "#/$defs/service_provider_capabilities" + }, + { + "$ref": "#/$defs/information_provider_capabilities" + }, + { + "$ref": "#/$defs/composite_service_capabilities" + }, + { + "$ref": "#/$defs/auth_provider_capabilities" + }, + { + "$ref": "#/$defs/peer_dcm_capabilities" + }, + { + "$ref": "#/$defs/process_provider_capabilities" + } + ] + }, + "provider_registration": { + "allOf": [ + { + "$ref": "#/$defs/base_provider_registration" + } + ], + "unevaluatedProperties": false + }, + "process_provider_capabilities": { + "type": "object", + "description": "Capabilities for process providers \u2014 ephemeral workflow execution (software install, backup, migration, compliance scan).", + "required": [ + "supported_process_types" + ], + "additionalProperties": false, + "properties": { + "supported_process_types": { + "type": "array", + "items": { + "type": "string" + }, + "description": "FQN process resource types this provider can execute" + }, + "max_concurrent_executions": { + "type": "integer" + }, + "timeout_default": { + "type": "string", + "description": "ISO 8601 duration" + }, + "idempotent": { + "type": "boolean", + "description": "Whether re-execution is safe" + }, + "automation_platform": { + "type": "string", + "description": "e.g., AAP, Tekton, ArgoWorkflows" + } + } + }, + "auth_provider_capabilities": { + "type": "object", + "description": "Capabilities for auth providers \u2014 authentication, identity, and MFA services. Multiple auth providers support tenant-routed authentication.", + "required": [ + "auth_modes", + "token_format" + ], + "additionalProperties": false, + "properties": { + "auth_modes": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "oidc", + "saml", + "ldap", + "kerberos", + "mtls_cert" + ] + }, + "description": "Supported authentication protocols" + }, + "token_format": { + "type": "string", + "enum": [ + "jwt", + "opaque", + "saml_assertion" + ] + }, + "mfa_methods": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "totp", + "webauthn", + "hardware_token", + "push", + "sms" + ] + }, + "description": "Supported MFA methods" + }, + "rbac_model": { + "type": "string", + "enum": [ + "group_claims", + "role_claims", + "attribute_based" + ] + }, + "token_lifetime_seconds": { + "type": "integer" + }, + "supports_session_revocation": { + "type": "boolean" + }, + "federation_capable": { + "type": "boolean", + "description": "Can federate with peer auth providers" + } + } + } + }, + "$ref": "#/$defs/base_provider_registration" +} diff --git a/schemas/jsonschema/resource-type-spec-template.json b/schemas/jsonschema/resource-type-spec-template.json new file mode 100644 index 0000000..189996e --- /dev/null +++ b/schemas/jsonschema/resource-type-spec-template.json @@ -0,0 +1,364 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://dcm-project.io/schemas/resource-types/template/v1", + "title": "DCM Resource Type Extension Schema Template", + "description": "Template and authoring guide for Resource Type Extension schemas. Service Providers publish one schema per resource type they offer to the Resource Type Registry. DCM uses these schemas to validate request fields, populate the Service Catalog field explorer, and enforce field constraints. See data-model/05-resource-type-hierarchy.md and data-model/20-registry-governance.md.", + + "$defs": { + + "resource_type_spec": { + "type": "object", + "title": "Resource Type Specification", + "description": "The top-level object published to the Resource Type Registry for each resource type.", + "required": [ + "fqn", + "version", + "entity_type", + "ownership_model", + "display_name", + "description", + "registry_tier", + "spec_schema", + "lifecycle" + ], + "additionalProperties": false, + "properties": { + + "fqn": { + "type": "string", + "pattern": "^[A-Z][a-zA-Z0-9]+\\.[A-Z][a-zA-Z0-9]+$", + "description": "Fully-qualified resource type name. Format: .. Examples: Compute.VirtualMachine, Network.VLAN, Database.PostgreSQLInstance, Process.AnsiblePlaybook" + }, + + "version": { + "type": "string", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$", + "description": "Semantic version. Major version increments when the spec_schema has breaking changes (removed required fields, type changes). Minor for new optional fields. Patch for description/metadata updates." + }, + + "entity_type": { + "type": "string", + "enum": ["infrastructure_resource", "composite_resource", "process_resource"], + "description": "Which DCM entity type resources of this type produce. Determines lifecycle state machine, drift detection, TTL eligibility." + }, + + "ownership_model": { + "type": "string", + "enum": ["whole_allocation", "allocation", "shareable"], + "description": "whole_allocation: requesting Tenant owns the resource outright. allocation: resource is carved from a pool (declare pool_resource_type). shareable: multiple consumers reference the same resource." + }, + + "pool_resource_type": { + "type": "string", + "description": "Required when ownership_model is 'allocation'. FQN of the pool resource type this allocation comes from (e.g., if this type is Network.IPAddress, pool_resource_type might be Network.IPAddressPool)." + }, + + "allocatable_pool": { + "type": "boolean", + "default": false, + "description": "True if resources of this type act as allocation pools. When true, this resource type produces pool entities from which allocation entities are carved." + }, + + "display_name": { "type": "string", "maxLength": 64 }, + "description": { "type": "string", "maxLength": 1024 }, + "icon": { "type": "string", "format": "uri", "description": "URL to SVG icon for Service Catalog display" }, + "documentation": { "type": "string", "format": "uri", "description": "URL to operator documentation for this resource type" }, + + "registry_tier": { + "type": "string", + "enum": ["dcm_system", "verified_community", "organization"], + "description": "dcm_system: built-in DCM types. verified_community: reviewed by DCM project. organization: local to this DCM deployment." + }, + + "provider_uuid": { + "type": "string", + "format": "uuid", + "description": "UUID of the Service Provider that realizes this resource type." + }, + + "spec_schema": { + "type": "object", + "description": "JSON Schema for the resource-type-specific fields. These fields appear in the `spec` object on create/update requests and in the `realized_fields` on entities. Must be a valid JSON Schema.", + "$ref": "#/$defs/resource_spec_schema" + }, + + "constraint_visibility": { + "type": "string", + "enum": ["full", "partial", "none"], + "default": "full", + "description": "How much constraint detail is visible to consumers in the Service Catalog. full: all constraints shown. partial: labels shown, not values. none: field exists but constraints hidden." + }, + + "lifecycle": { + "type": "object", + "description": "Lifecycle configuration for this resource type.", + "required": ["supports_suspension", "supports_rehydration"], + "additionalProperties": false, + "properties": { + "supports_suspension": { "type": "boolean" }, + "supports_rehydration": { "type": "boolean" }, + "default_ttl": { "type": "string", "description": "ISO 8601 duration. If set, resources get this TTL by default." }, + "max_ttl": { "type": "string", "description": "ISO 8601 duration. Maximum allowed TTL." }, + "on_expiry_default": { "type": "string", "enum": ["decommission", "suspend", "notify", "escalate"] } + } + }, + + "drift_detection": { + "type": "object", + "description": "Drift detection configuration for this resource type.", + "additionalProperties": false, + "properties": { + "enabled": { "type": "boolean", "default": true }, + "field_criticality": { + "type": "object", + "additionalProperties": { + "type": "string", + "enum": ["critical", "significant", "minor"] + }, + "description": "Map of field_path → criticality. Fields not listed default to 'minor'. Criticality × change magnitude = drift severity." + } + } + }, + + "relationships": { + "type": "object", + "description": "Permitted relationship types for resources of this type.", + "additionalProperties": false, + "properties": { + "requires": { + "type": "array", + "items": { "type": "string" }, + "description": "Resource type FQNs this resource type requires (hard dependencies)" + }, + "supports_references_to": { + "type": "array", + "items": { "type": "string" }, + "description": "Resource type FQNs this resource type may reference (soft dependencies)" + } + } + }, + + "catalog_metadata": { + "type": "object", + "description": "Service Catalog presentation metadata.", + "additionalProperties": false, + "properties": { + "category": { "type": "string" }, + "tags": { "type": "array", "items": { "type": "string" } }, + "cost_unit": { "type": "string", "description": "What the cost is denominated in (e.g., 'per vCPU/month')" }, + "typical_provisioning_time": { "type": "string", "description": "ISO 8601 duration estimate" } + } + }, + + "deprecated": { + "type": "object", + "description": "Present if this resource type is deprecated.", + "additionalProperties": false, + "properties": { + "since_version": { "type": "string" }, + "sunset_at": { "type": "string", "format": "date-time" }, + "successor_type": { "type": "string", "description": "FQN of the replacement resource type" }, + "migration_guide":{ "type": "string", "format": "uri" } + } + } + } + }, + + "resource_spec_schema": { + "type": "object", + "description": "The JSON Schema for resource-type-specific fields. This is an embedded JSON Schema document. It defines what fields appear in the `spec` object of create/update requests and in the `realized_fields` of entities.", + "required": ["type", "properties"], + "properties": { + "type": { "const": "object" }, + "properties": { "type": "object" }, + "required": { "type": "array", "items": { "type": "string" } }, + "additionalProperties": { "type": "boolean", "default": false } + } + }, + + "field_descriptor": { + "type": "object", + "description": "A field in the resource spec_schema. Extends standard JSON Schema with DCM-specific metadata.", + "properties": { + "type": { "type": "string" }, + "description": { "type": "string" }, + "x-dcm-editable": { + "type": "boolean", + "default": false, + "description": "Whether this field can be changed on a REALIZED/OPERATIONAL resource via PATCH /resources/{uuid}" + }, + "x-dcm-provider-only": { + "type": "boolean", + "default": false, + "description": "Field is populated by the provider on realization and cannot be set by the consumer on request" + }, + "x-dcm-immutable": { + "type": "boolean", + "default": false, + "description": "Field cannot be changed after initial request (not editable, not updated by provider)" + }, + "x-dcm-display": { + "type": "string", + "enum": ["visible", "hidden", "admin_only"], + "default": "visible", + "description": "Service Catalog visibility for this field" + }, + "x-dcm-constraint-basis": { + "type": "string", + "description": "Human-readable explanation of why this constraint exists (displayed in Service Catalog)" + }, + "x-dcm-example": { + "description": "Example value shown in Service Catalog field explorer" + } + } + } + + }, + + "type": "object", + "title": "Resource Type Extension Schema — Example (Compute.VirtualMachine)", + "description": "Example showing how a Service Provider would define the Resource Type Spec for Compute.VirtualMachine. Replace all fields with your resource type specifics.", + + "properties": { + "resource_type_spec": { "$ref": "#/$defs/resource_type_spec" } + }, + + "examples": [ + { + "resource_type_spec": { + "fqn": "Compute.VirtualMachine", + "version": "1.2.0", + "entity_type": "infrastructure_resource", + "ownership_model": "whole_allocation", + "display_name": "Virtual Machine", + "description": "A virtual machine instance on the organization's virtualization infrastructure.", + "registry_tier": "organization", + "provider_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + + "spec_schema": { + "type": "object", + "required": ["cpu_cores", "memory_gb", "os_image"], + "additionalProperties": false, + "properties": { + + "cpu_cores": { + "type": "integer", + "minimum": 1, + "maximum": 128, + "description": "Number of vCPUs", + "x-dcm-editable": true, + "x-dcm-display": "visible", + "x-dcm-constraint-basis": "Maximum set by hypervisor NUMA topology", + "x-dcm-example": 4 + }, + + "memory_gb": { + "type": "integer", + "minimum": 1, + "maximum": 1024, + "description": "RAM in gigabytes", + "x-dcm-editable": true, + "x-dcm-display": "visible", + "x-dcm-example": 8 + }, + + "os_image": { + "type": "string", + "description": "OS image identifier", + "x-dcm-editable": false, + "x-dcm-immutable": true, + "x-dcm-display": "visible", + "x-dcm-example": "rhel-9-approved-2026-03" + }, + + "os_image_version": { + "type": "string", + "description": "Current patched OS version", + "x-dcm-provider-only": true, + "x-dcm-display": "visible" + }, + + "network_segment_uuid": { + "type": "string", + "format": "uuid", + "description": "UUID of the Network.Segment resource to attach to", + "x-dcm-editable": false, + "x-dcm-immutable": true + }, + + "ip_address": { + "type": "string", + "format": "ipv4", + "description": "Assigned IP address (provider-assigned)", + "x-dcm-provider-only": true, + "x-dcm-display": "visible" + }, + + "hostname": { + "type": "string", + "pattern": "^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$", + "description": "VM hostname. If not provided, generated by the provider.", + "x-dcm-editable": false, + "x-dcm-example": "prod-app-01" + }, + + "storage_volumes": { + "type": "array", + "items": { + "type": "object", + "required": ["size_gb"], + "properties": { + "size_gb": { "type": "integer", "minimum": 10 }, + "type": { "type": "string", "enum": ["ssd", "hdd", "nvme"] }, + "mount_point": { "type": "string" } + } + }, + "x-dcm-editable": true, + "description": "Additional storage volumes. Root volume is always included." + }, + + "hypervisor_host": { + "type": "string", + "description": "Hypervisor host where the VM was placed", + "x-dcm-provider-only": true, + "x-dcm-display": "admin_only" + } + } + }, + + "lifecycle": { + "supports_suspension": true, + "supports_rehydration": true, + "default_ttl": null, + "on_expiry_default": "notify" + }, + + "drift_detection": { + "enabled": true, + "field_criticality": { + "cpu_cores": "significant", + "memory_gb": "significant", + "os_image_version": "critical", + "ip_address": "critical", + "network_segment_uuid":"critical", + "hostname": "significant", + "storage_volumes": "significant", + "hypervisor_host": "minor" + } + }, + + "relationships": { + "requires": ["Network.Segment"], + "supports_references_to": ["Network.IPAddressPool", "Storage.Volume"] + }, + + "catalog_metadata": { + "category": "Compute", + "tags": ["virtual-machine", "compute", "vm"], + "cost_unit": "per vCPU/month", + "typical_provisioning_time": "PT3M" + } + } + } + ] +}