Grabadora Asset Core Puerta de Decisión
Docs
Documentos de Decision Gate

Evaluación de puertas determinista, reproducible con decisiones auditables.

Documentación de Asset Core

typedprovidersimport

Importar OpenAPI en artefactos de proveedor tipados y registrar una versión de perfil.

Notas clave

  • Requiere los campos de ámbito tenant_id y namespace_id.
  • La importación estricta que falla en cerrado requiere una lista de operaciones permitidas explícita.
  • Requiere un mapeo explícito de credential_bindings; use {} para importaciones no autenticadas.
  • Soporta límites de salida acotados y una política de reintentos para los perfiles de tiempo de ejecución generados.
  • Genera artefactos de contrato de proveedor determinista + perfil de tiempo de ejecución.
  • Registra metadatos del ciclo de vida y, opcionalmente, activa la versión importada.

Entradas

  • activate (opcional): Activa esta versión después del registro.
  • allow_unsafe_methods (opcional): Permitir métodos HTTP no seguros durante la importación.
  • credential_bindings (requerido): id del esquema de seguridad OpenAPI para metadatos de enlace de credenciales estructuradas (localizador + valor_render). Use {} para importaciones no autenticadas.
  • external_ref_mode (opcional): Política de resolución de $ref externa opcional.
  • max_response_bytes (opcional): Límite de tamaño de respuesta en tiempo de ejecución opcional.
  • media_support_mode (opcional): Modo de soporte de medios opcional.
  • namespace_id (requerido): Identificador de espacio de nombres.
  • openapi (requerido): Documento OpenAPI 3.x en formato JSON.
  • openapi_conformance_mode (opcional): Modo de conformidad: estricto bloquea construcciones no soportadas; informes de auditoría sin activación.
  • openapi_semantics_mode (opcional): Anulación opcional del modo de semántica OpenAPI.
  • openapi_source_path (opcional): Ruta de origen opcional utilizada para resolver referencias de archivos locales.
  • operation_allowlist (requerido): Lista de permitidos de operationId explícita para importación estricta.
  • outbound_max_inflight (opcional): Anulación opcional del límite de inflight saliente.
  • provider_id (requerido): Identificador de proveedor tipado.
  • retry_initial_backoff_ms (opcional): Sobrescritura opcional del retroceso inicial de reintento saliente.
  • retry_max_attempts (opcional): Sobrescritura opcional del número máximo de intentos de reintento saliente.
  • retry_max_backoff_ms (opcional): Anulación opcional del tiempo máximo de espera para reintentos salientes.
  • tenant_id (required): Identificador del inquilino.
  • timeout_ms (opcional): Sobrescritura opcional del tiempo de espera en milisegundos.
  • version (requerido): Identificador de versión del ciclo de vida.

Esquema de Entrada

{
  "$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"
}

Salidas

  • active_version (requerido): Una de 2 variantes de esquema.
  • conformance_summary (requerido): Tipo: object.
  • contract_hash (requerido): Tipo: object.
  • operation_count (requerido): Tipo: entero.
  • profile_digest (requerido): Tipo: object.
  • provider_id (requerido): Identificador de proveedor tipado.
  • register_outcome (requerido): Resultado del registro del ciclo de vida del perfil tipado.
  • source_digest (requerido): Tipo: objeto.
  • version (requerido): Identificador de versión del ciclo de vida.

Esquema de Salida

{
  "$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"
}

Ejemplos

Importar un documento OpenAPI en artefactos tipados.

Entrada:

{
  "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"
}