typedprovidersimport
Importa OpenAPI en artefactes de proveïdor tipats i registra una versió de perfil.
Notes clau
- Requereix els camps de l’abast tenant_id i namespace_id.
- La importació estrictament tancada requereix una llista d’operacions explícita permesa.
- Requereix un mapeig explícit de credential_bindings; utilitzeu {} per a importacions no autenticades.
- Suporta límits de sortida delimitats i una política de reintents per a perfils d’execució generats.
- Genera artefactes de contracte de proveïdor determinístic + perfil d’execució.
- Registra metadades del cicle de vida i opcionalment activa la versió importada.
Inputs
activate(opcional): Activa aquesta versió després del registre.allow_unsafe_methods(opcional): Permetre mètodes HTTP no segurs durant la importació.credential_bindings(requerit): id del esquema de seguretat OpenAPI per a metadades de vinculació de credencials estructurades (localitzador + valor_render). Utilitzeu {} per a importacions no autenticades.external_ref_mode(opcional): Política de resolució de $ref externa opcional.max_response_bytes(opcional): Sobrecàrrega opcional del límit de mida de resposta en temps d’execució.media_support_mode(opcional): Mode de suport multimèdia opcional.- namespace_id (requerit): Identificador de l’espai de noms.
openapi(requerit): document OpenAPI 3.x com a JSON.openapi_conformance_mode(opcional): Mode de conformitat: els blocs estrictes bloquegen construccions no compatibles; informes d’auditoria sense activació.openapi_semantics_mode(opcional): Sobreescriptura opcional del mode de semàntica OpenAPI.openapi_source_path(opcional): Ruta de font opcional utilitzada per resoldre referències de fitxers locals.operation_allowlist(requerit): Llista d’operacions explícites allowlist per a una importació estricta.outbound_max_inflight(opcional): Sobrecàrrega opcional del límit d’inflight sortint.provider_id(requerit): Identificador del proveïdor tipat.retry_initial_backoff_ms(opcional): Substitució opcional de l’espera inicial de reintents sortints.retry_max_attempts(opcional): Sobrecàrrega opcional del màxim nombre d’intents de reintents sortints.retry_max_backoff_ms(opcional): Sobrecàrrega opcional del màxim retrocés de reintents sortints.- tenant_id (required): Identificador del llogater.
timeout_ms(opcional): Sobrecàrrega opcional de temps d’execució en mil·lisegons.version(requerit): Identificador de la versió del cicle de vida.
Input Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"activate": {
"description": "Activate this version after registration.",
"type": "boolean"
},
"allow_unsafe_methods": {
"description": "Allow non-safe HTTP methods during import.",
"type": "boolean"
},
"credential_bindings": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"display_name": {
"description": "Optional non-secret operator label.",
"minLength": 1,
"type": "string"
},
"locator": {
"description": "Credential locator URI (secret://... or env://...).",
"minLength": 1,
"type": "string"
},
"value_render": {
"description": "Deterministic wire-value render policy for the raw secret.",
"oneOf": [
{
"additionalProperties": false,
"properties": {
"mode": {
"const": "identity"
}
},
"required": [
"mode"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"mode": {
"const": "prefix"
},
"prefix": {
"description": "Prefix prepended to the raw secret before injection.",
"minLength": 1,
"type": "string"
}
},
"required": [
"mode",
"prefix"
],
"type": "object"
}
]
}
},
"required": [
"locator",
"value_render"
],
"type": "object"
},
"description": "OpenAPI security scheme id to structured credential binding metadata (locator + value_render). Use {} for unauthenticated imports.",
"propertyNames": {
"minLength": 1,
"type": "string"
},
"type": "object"
},
"external_ref_mode": {
"description": "Optional external $ref resolution policy.",
"enum": [
"local_file_only",
"network_allowlist"
],
"type": "string"
},
"max_response_bytes": {
"description": "Optional runtime response-size limit override.",
"maximum": 1048576,
"minimum": 1,
"type": "integer"
},
"media_support_mode": {
"description": "Optional media support mode.",
"enum": [
"json_only",
"all_media"
],
"type": "string"
},
"namespace_id": {
"description": "Namespace identifier.",
"minimum": 1,
"type": "integer"
},
"openapi": {
"description": "OpenAPI 3.x document as JSON.",
"type": [
"null",
"boolean",
"number",
"string",
"array",
"object"
]
},
"openapi_conformance_mode": {
"description": "Conformance mode: strict blocks unsupported constructs; audit reports without activation.",
"enum": [
"strict",
"audit"
],
"type": "string"
},
"openapi_semantics_mode": {
"description": "Optional OpenAPI semantics mode override.",
"enum": [
"auto",
"oas30",
"oas31"
],
"type": "string"
},
"openapi_source_path": {
"description": "Optional source path used to resolve local-file refs.",
"type": "string"
},
"operation_allowlist": {
"description": "Explicit operationId allowlist for strict import.",
"items": {
"description": "OpenAPI operationId allowlist entry.",
"type": "string"
},
"maxItems": 256,
"minItems": 1,
"type": "array"
},
"outbound_max_inflight": {
"description": "Optional outbound inflight limit override.",
"maximum": 1024,
"minimum": 1,
"type": "integer"
},
"provider_id": {
"description": "Typed provider identifier.",
"type": "string"
},
"retry_initial_backoff_ms": {
"description": "Optional outbound retry initial-backoff override.",
"maximum": 60000,
"minimum": 1,
"type": "integer"
},
"retry_max_attempts": {
"description": "Optional outbound retry max-attempts override.",
"maximum": 8,
"minimum": 1,
"type": "integer"
},
"retry_max_backoff_ms": {
"description": "Optional outbound retry max-backoff override.",
"maximum": 60000,
"minimum": 1,
"type": "integer"
},
"tenant_id": {
"description": "Tenant identifier.",
"minimum": 1,
"type": "integer"
},
"timeout_ms": {
"description": "Optional runtime timeout override in milliseconds.",
"maximum": 30000,
"minimum": 100,
"type": "integer"
},
"version": {
"description": "Lifecycle version identifier.",
"type": "string"
}
},
"required": [
"tenant_id",
"namespace_id",
"provider_id",
"version",
"openapi",
"operation_allowlist",
"credential_bindings"
],
"type": "object"
}
Sortides
active_version(requerit): Una de les 2 variants d’esquema.conformance_summary(requerit): Tipus: objecte.- contract_hash (requerit): Tipus: object.
operation_count(requerit): Tipus: enter.profile_digest(requerit): Tipus: objecte.provider_id(requerit): Identificador del proveïdor tipat.register_outcome(requerit): Resultat del registre del cicle de vida del perfil tipificat.source_digest(obligatori): Tipus: objecte.version(requerit): Identificador de la versió del cicle de vida.
Esquema de sortida
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"active_version": {
"oneOf": [
{
"type": "null"
},
{
"description": "Current active lifecycle version.",
"type": "string"
}
]
},
"conformance_summary": {
"additionalProperties": false,
"properties": {
"activation_allowed": {
"type": "boolean"
},
"import_mode": {
"enum": [
"strict",
"audit"
],
"type": "string"
},
"supported_feature_hits": {
"description": "Sorted unique supported feature ids observed during import.",
"items": {
"description": "Observed supported feature id.",
"type": "string"
},
"type": "array"
},
"supported_features_covered": {
"minimum": 0,
"type": "integer"
},
"unsupported_codes": {
"items": {
"description": "Unsupported taxonomy code.",
"type": "string"
},
"type": "array"
},
"unsupported_construct_count": {
"minimum": 0,
"type": "integer"
},
"unsupported_findings": {
"items": {
"additionalProperties": false,
"properties": {
"code": {
"description": "Stable unsupported taxonomy code.",
"type": "string"
},
"construct": {
"description": "Unsupported construct label.",
"type": "string"
},
"doc_ref": {
"description": "Documentation reference for this unsupported taxonomy entry.",
"type": "string"
},
"location": {
"description": "Location label for the finding.",
"type": "string"
},
"message": {
"description": "Deterministic finding message.",
"type": "string"
},
"operation_id": {
"oneOf": [
{
"type": "null"
},
{
"description": "Operation id, when available.",
"type": "string"
}
]
},
"pointer": {
"oneOf": [
{
"type": "null"
},
{
"description": "JSON pointer for the finding location.",
"type": "string"
}
]
},
"rationale": {
"description": "Rationale from unsupported taxonomy.",
"type": "string"
},
"remediation": {
"description": "Remediation guidance from unsupported taxonomy.",
"type": "string"
},
"severity": {
"description": "Severity level from unsupported taxonomy.",
"enum": [
"critical",
"high",
"medium",
"low"
],
"type": "string"
}
},
"required": [
"code",
"construct",
"severity",
"rationale",
"remediation",
"doc_ref",
"message",
"location",
"operation_id",
"pointer"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"supported_features_covered",
"supported_feature_hits",
"unsupported_construct_count",
"unsupported_codes",
"import_mode",
"activation_allowed",
"unsupported_findings"
],
"type": "object"
},
"contract_hash": {
"additionalProperties": false,
"properties": {
"algorithm": {
"enum": [
"sha256"
],
"type": "string"
},
"value": {
"description": "Lowercase hex digest.",
"type": "string"
}
},
"required": [
"algorithm",
"value"
],
"type": "object"
},
"operation_count": {
"minimum": 0,
"type": "integer"
},
"profile_digest": {
"additionalProperties": false,
"properties": {
"algorithm": {
"enum": [
"sha256"
],
"type": "string"
},
"value": {
"description": "Lowercase hex digest.",
"type": "string"
}
},
"required": [
"algorithm",
"value"
],
"type": "object"
},
"provider_id": {
"description": "Typed provider identifier.",
"type": "string"
},
"register_outcome": {
"description": "Typed profile lifecycle registration outcome.",
"enum": [
"registered",
"already_registered"
],
"type": "string"
},
"source_digest": {
"additionalProperties": false,
"properties": {
"algorithm": {
"enum": [
"sha256"
],
"type": "string"
},
"value": {
"description": "Lowercase hex digest.",
"type": "string"
}
},
"required": [
"algorithm",
"value"
],
"type": "object"
},
"version": {
"description": "Lifecycle version identifier.",
"type": "string"
}
},
"required": [
"provider_id",
"version",
"register_outcome",
"active_version",
"source_digest",
"profile_digest",
"contract_hash",
"operation_count",
"conformance_summary"
],
"type": "object"
}
Exemples
Importa un document OpenAPI en artefactes tipats.
Input:
{
"activate": true,
"allow_unsafe_methods": false,
"credential_bindings": {},
"external_ref_mode": "local_file_only",
"max_response_bytes": 1048576,
"media_support_mode": "json_only",
"namespace_id": 1,
"openapi": {
"openapi": "3.1.0",
"paths": {
"/assets": {
"get": {
"operationId": "listAssets",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"items": {
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
}
}
},
"description": "ok"
}
}
}
}
}
},
"openapi_conformance_mode": "strict",
"openapi_semantics_mode": "auto",
"operation_allowlist": [
"listAssets"
],
"outbound_max_inflight": 32,
"provider_id": "asset_api",
"retry_initial_backoff_ms": 100,
"retry_max_attempts": 3,
"retry_max_backoff_ms": 2000,
"tenant_id": 1,
"timeout_ms": 5000,
"version": "2026-02-17.1"
}
Output:
{
"active_version": "2026-02-17.1",
"conformance_summary": {
"activation_allowed": true,
"import_mode": "strict",
"supported_feature_hits": [
"openapi.version.3_1"
],
"supported_features_covered": 1,
"unsupported_codes": [],
"unsupported_construct_count": 0,
"unsupported_findings": []
},
"contract_hash": {
"algorithm": "sha256",
"value": "5c3a5b6bce0f4a2c9e22c4fa6a1e6d8d90b0f2dfed1b7f1e9b3d3b3d1f0c9b21"
},
"operation_count": 1,
"profile_digest": {
"algorithm": "sha256",
"value": "5c3a5b6bce0f4a2c9e22c4fa6a1e6d8d90b0f2dfed1b7f1e9b3d3b3d1f0c9b21"
},
"provider_id": "asset_api",
"register_outcome": "registered",
"source_digest": {
"algorithm": "sha256",
"value": "5c3a5b6bce0f4a2c9e22c4fa6a1e6d8d90b0f2dfed1b7f1e9b3d3b3d1f0c9b21"
},
"version": "2026-02-17.1"
}