API Evangelist enhancements for the Experian Aperture Data Quality API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Experian Aperture Data Quality API
  version: 1.0.0
extends: openapi/experian-aperture-openapi.json
x-generated: '2026-09-13'
x-method: generated
x-source: openapi/experian-aperture-openapi.json plus the artifacts derived from it in this repo
x-note: >-
  This overlay records API Evangelist enhancements to Experian's published contract. It NEVER mutates
  the original document. Two gaps drove it. First, not one of the 41 operations in Experian's
  published spec carries an operationId — measured, zero of 41 — which makes the contract unusable by
  every code generator and every tool that binds a tool name to an operation, and is why the agent
  skills in this repo have to address operations by method and path. This overlay does not invent
  operationIds into the provider's document; it records the gap as an extension so the absence is
  legible rather than silent. Second, the runtime semantics Experian documents on web pages —
  the account-wide 150 req/min limit and its X-Rate-Limit-* headers, the rfc9457-shaped error
  envelope, the reversibility posture of the two write surfaces — appear nowhere in the contract, so
  an agent reading only the spec cannot see them.
actions:
  - target: $.info
    description: Record the contract-quality gaps measured against the published document and point
      at the derived artifacts that fill them.
    update:
      x-api-evangelist:
        measured: '2026-09-13'
        operations: 41
        operations_with_operationid: 0
        operations_with_summary: 41
        operations_with_description: 0
        operations_with_tags: 41
        components_schemas: 389
        spec_declares_tags_array: false
        note: >-
          Every operation has a summary and a tag but none has an operationId and none has a
          description. The document also declares no top-level tags[] array, so the tag names used on
          operations are undescribed. These are the highest-leverage single fixes available to
          Experian in this contract.
        derived_artifacts:
          authentication: authentication/experian-authentication.yml
          conventions: conventions/experian-conventions.yml
          errors: errors/experian-problem-types.yml
          rate_limits: rate-limits/experian-rate-limits.yml
          lifecycle: lifecycle/experian-lifecycle.yml
          data_model: data-model/experian-data-model.yml
          conformance: conformance/experian-conformance.yml
          mcp_candidate: mcp/experian-mcp.yml
  - target: $.info
    description: Attach the published contact and licensing context absent from info.
    update:
      x-documentation-url: https://docs.experianaperture.io/
      x-support-url: https://community.experianaperture.io/
      x-status-page: https://status.edq.com/
      x-terms-url: https://docs.experianaperture.io/standard-terms-and-conditions-and-policies
      x-sla-url: https://docs.experianaperture.io/saas-services-sla
      x-eosl-url: https://docs.experianaperture.io/end-of-service-life-status
  - target: $.info
    description: Record the runtime rate-limit contract, which the spec does not express.
    update:
      x-rate-limit:
        scope: per-account
        window: 1 minute
        limit: 150
        adjustable: false
        status_on_exhaustion: 429
        headers:
          - X-Rate-Limit-Limit
          - X-Rate-Limit-Remaining
          - X-Rate-Limit-Reset
        retry_after: false
        source: https://docs.experianaperture.io/address-validation/experian-address-validation/help/rate-limiting/
  - target: $.info
    description: Record the error-envelope semantics and the fact that the RFC 9457 media type is
      not used.
    update:
      x-error-format:
        shape: rfc9457-shaped
        media_type: application/json
        problem_json: false
        wrapper: error
        members:
          - type
          - title
          - detail
          - instance
        missing_members:
          - status
        catalog: errors/experian-problem-types.yml
  - target: $.info
    description: Record the agent-safety posture of the surface — idempotency, dry-run and
      reversibility — none of which the contract expresses.
    update:
      x-agent-safety:
        idempotency:
          coverage: none
          header: null
        dry_run: false
        reversibility:
          grade: documented
          reversible_writes:
            - surface: bulk batches
              reversal: POST /{address|email|phone}/bulk/v1/batches/{batch_id}/stop
              window_stated: false
          irreversible_writes:
            - surface: custom address layouts
              operation: DELETE /address/layouts/v2/{name}
              note: no restore or soft-delete is documented
        read_only_majority: true
        pii_operations:
          - POST /enrichment/v2
          - POST /identity/append/v1
          - POST /phone/append/v1
        pii_note: >-
          These three operations return personal or household-level data about identifiable people.
          Any agent integration should treat them as consent-gated regardless of what the API
          permits, and any use in the United States falls under FCRA permissible-purpose rules.
  - target: $.components.securitySchemes.Auth-Token
    description: Record the operational controls attached to the token that the scheme description
      omits.
    update:
      x-issued-from: https://docs.experianaperture.io/more/self-service-portal/
      x-additional-controls:
        - per-integration domain allowlist (403 when the calling domain is not allowlisted)
        - per-integration IP allowlist (403 when the calling IP is not allowlisted)
      x-environment-selection: by hostname, not by key prefix — a token's value does not reveal
        whether it is test or live
  - target: $.servers
    description: Note that the single declared server is the only Aperture host; the Global
      Developer Platform is a separate, region-partitioned surface with no published contract.
    update:
      x-related-platforms:
        - name: Experian Global Developer Platform
          hosts:
            - https://us-api.experian.com
            - https://uk-api.experian.com
            - https://eu-api.experian.com
            - https://api.experian.com.au
          contract_published: false
          portal: https://developer.experian.com/