> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Get what a document's file needs

> Returns the contract: every set the file carries, every field of it, its type, whether it is required and how it is formatted. It is what a client reads to understand what they are mapping, and it is curated — never uploaded.



## OpenAPI

````yaml /en/openapi/v3-current/reporter.yaml get /v1/regulatory/documents/{documentId}/contract
openapi: 3.1.0
info:
  contact:
    name: Discord community
    url: https://discord.gg/DnhqKwkGv3
  description: >-
    This is OpenAPI documentation for Reporter. The unified reporter binary
    serves the REST API (RUN_MODE=api) and/or the RabbitMQ report-generation
    worker (RUN_MODE=worker); RUN_MODE=all runs both in one process for local
    development. All REST endpoints documented here serve only when RUN_MODE=api
    or all (port :4005); the worker (port :4006) exposes health/readyz/version
    only.
  license:
    name: Lerian Studio General License
  title: Midaz Reporter API
  version: 4.0.0
servers:
  - url: http://localhost:4005
  - url: https://localhost:4005
security:
  - BearerAuth: []
tags:
  - description: Generated report instances and their lifecycle.
    name: Reports
  - description: Reusable report definitions.
    name: Templates
  - description: Interactive construction of report templates.
    name: Template Builder
  - description: Scheduled report due-date tracking.
    name: Deadlines
  - description: Configured inputs that feed report data.
    name: Data Sources
  - description: Aggregated reporting metrics.
    name: Metrics
  - description: Published business event catalog and delivery policies.
    name: Streaming
paths:
  /v1/regulatory/documents/{documentId}/contract:
    get:
      tags:
        - Regulatory Catalog
      summary: Get what a document's file needs
      description: >-
        Returns the contract: every set the file carries, every field of it, its
        type, whether it is required and how it is formatted. It is what a
        client reads to understand what they are mapping, and it is curated —
        never uploaded.
      operationId: getRegulatoryDocumentContract
      parameters:
        - description: Document identifier, as the catalog publishes it.
          example: br.bcb.cadoc-4010
          in: path
          name: documentId
          required: true
          schema:
            description: Document identifier, as the catalog publishes it.
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegulatoryContractWire'
          description: OK
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Not Found
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Internal Server Error
components:
  schemas:
    RegulatoryContractWire:
      additionalProperties: false
      properties:
        apiVersion:
          description: Format identifier of the contract document.
          examples:
            - reporter.lerian.io/v1alpha1
          type: string
        datasets:
          description: Every set the file carries and every field of it.
          items:
            $ref: '#/components/schemas/RegulatoryDatasetWire'
          type:
            - array
            - 'null'
        kind:
          description: Document kind; always DocumentContract.
          examples:
            - DocumentContract
          type: string
        knownGaps:
          description: What this contract knowingly does not yet cover.
          items:
            $ref: '#/components/schemas/RegulatoryKnownGapWire'
          type:
            - array
            - 'null'
        metadata:
          $ref: '#/components/schemas/RegulatoryMetadataWire'
          description: Which obligation this is, at which version.
        parameters:
          description: What the generation must be told, answered per request.
          items:
            $ref: '#/components/schemas/RegulatoryParameterWire'
          type:
            - array
            - 'null'
        rules:
          description: Assertions the finished file must satisfy.
          items:
            $ref: '#/components/schemas/RegulatoryRuleWire'
          type:
            - array
            - 'null'
      required:
        - metadata
        - parameters
        - datasets
        - rules
        - knownGaps
      type: object
    Detail:
      properties:
        code:
          description: >-
            Stable, machine-readable domain error code scoped to the emitting
            service (format: <SERVICE>-NNNN).
          type: string
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          examples:
            - - location: body.templateId
                message: expected string to match 'uuid' format
                value: not-a-uuid
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
        upstream:
          $ref: '#/components/schemas/Upstream'
          description: >-
            RFC 9457 extension member: the error a proxied third-party provider
            reported. Absent unless the emitting service explicitly surfaced
            one.
      type: object
    RegulatoryDatasetWire:
      additionalProperties: false
      properties:
        childOf:
          $ref: '#/components/schemas/RegulatoryChildOfWire'
          description: Present when this set is a nested list on each row of another.
        description:
          type: string
        fields:
          items:
            $ref: '#/components/schemas/RegulatoryFieldWire'
          type:
            - array
            - 'null'
        grain:
          $ref: '#/components/schemas/RegulatoryGrainWire'
          description: Row shape the file requires of this set.
        means:
          description: What the set represents, in prose, for whoever writes the mapping.
          type: string
        name:
          examples:
            - cosif_balances
          type: string
        rowSet:
          $ref: '#/components/schemas/RegulatoryRowSetWire'
          description: Present when the ROWS come from the catalog rather than the client.
      required:
        - name
        - grain
        - fields
      type: object
    RegulatoryKnownGapWire:
      additionalProperties: false
      properties:
        description:
          type: string
        id:
          type: string
      required:
        - id
      type: object
    RegulatoryMetadataWire:
      additionalProperties: false
      properties:
        appliesTo:
          $ref: '#/components/schemas/RegulatoryAppliesToWire'
          description: Which institutions owe this document.
        country:
          examples:
            - BR
          type: string
        document:
          description: The regulator's own number for it.
          examples:
            - '4010'
          type: string
        id:
          description: Document identifier, as a subscription names it.
          examples:
            - br.bcb.cadoc-4010
          type: string
        layout:
          $ref: '#/components/schemas/RegulatoryLayoutWire'
          description: >-
            Layout edition this contract is written against, on a document with
            more than one.
        output:
          description: File format the regulator receives.
          examples:
            - xml
          type: string
        periodicity:
          examples:
            - monthly
          type: string
        regulator:
          examples:
            - BCB
          type: string
        status:
          examples:
            - stable
          type: string
        title:
          examples:
            - Balancete Patrimonial Analítico
          type: string
        version:
          examples:
            - 1.0.0
          type: string
      required:
        - id
        - appliesTo
      type: object
    RegulatoryParameterWire:
      additionalProperties: false
      properties:
        allowedMonths:
          description: >-
            Months of any year this parameter may name, as two-digit numbers.
            Null when any month is allowed.
          items:
            type: string
          type:
            - array
            - 'null'
        default:
          description: >-
            Applied when the request omits the parameter. Null when the
            parameter has none — an empty string is a declared default of empty,
            which is a different thing.
          type:
            - string
            - 'null'
        description:
          type: string
        domain:
          description: >-
            Closed set of values the parameter accepts. Null when it is not
            narrowed.
          items:
            type: string
          type:
            - array
            - 'null'
        name:
          examples:
            - dataBase
          type: string
        required:
          type: boolean
        type:
          examples:
            - month
          type: string
      required:
        - name
        - type
        - required
        - default
        - domain
        - allowedMonths
      type: object
    RegulatoryRuleWire:
      additionalProperties: false
      properties:
        appliesTo:
          type: string
        assert:
          type: string
        id:
          type: string
        message:
          type: string
        severity:
          examples:
            - error
          type: string
      required:
        - id
        - severity
        - assert
      type: object
    ErrorDetail:
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          examples:
            - body.templateId
          type: string
        message:
          description: Error message text
          examples:
            - expected string to match 'uuid' format
          type: string
        value:
          description: The value at the given location
          examples:
            - not-a-uuid
      type: object
    Upstream:
      additionalProperties: false
      properties:
        code:
          description: The upstream provider's own error code, verbatim.
          examples:
            - E4001
          type: string
        message:
          description: >-
            The upstream provider's own error message, verbatim (bounded, never
            its raw response body).
          examples:
            - account not found at provider
          type: string
      type: object
    RegulatoryChildOfWire:
      additionalProperties: false
      properties:
        dataset:
          description: Parent set this one hangs from.
          type: string
      required:
        - dataset
      type: object
    RegulatoryFieldWire:
      additionalProperties: false
      properties:
        description:
          type: string
        domain:
          items:
            type: string
          type:
            - array
            - 'null'
        equalsSumOf:
          $ref: '#/components/schemas/RegulatoryReferenceWire'
        forbiddenWhen:
          $ref: '#/components/schemas/RegulatoryConditionWire'
        format:
          $ref: '#/components/schemas/RegulatoryFormatWire'
        length:
          description: Exact length the file requires, when it requires one.
          format: int64
          type: integer
        means:
          type: string
        name:
          examples:
            - saldo
          type: string
        normalize:
          type: string
        pattern:
          type: string
        refersTo:
          $ref: '#/components/schemas/RegulatoryReferenceWire'
        required:
          type: boolean
        requiredWhen:
          $ref: '#/components/schemas/RegulatoryConditionWire'
        type:
          examples:
            - decimal
          type: string
      required:
        - name
        - type
        - required
      type: object
    RegulatoryGrainWire:
      additionalProperties: false
      properties:
        keys:
          description: Fields whose combination is unique across the set.
          items:
            type: string
          type:
            - array
            - 'null'
        singleton:
          description: True when the set is always exactly one row.
          type: boolean
      required:
        - singleton
      type: object
    RegulatoryRowSetWire:
      additionalProperties: false
      properties:
        key:
          description: Field of this set each catalog-supplied row is identified by.
          type: string
      required:
        - key
      type: object
    RegulatoryAppliesToWire:
      additionalProperties: false
      properties:
        institutionTypes:
          items:
            type: string
          type:
            - array
            - 'null'
      type: object
    RegulatoryLayoutWire:
      additionalProperties: false
      properties:
        mandatoryFrom:
          description: First data-base this layout applies to, as AAAA-MM-DD.
          examples:
            - '2026-01-01'
          type: string
        version:
          type: string
      type: object
    RegulatoryReferenceWire:
      additionalProperties: false
      properties:
        dataset:
          type: string
        field:
          type: string
      required:
        - dataset
        - field
      type: object
    RegulatoryConditionWire:
      additionalProperties: false
      properties:
        field:
          type: string
        operator:
          type: string
        values:
          items:
            type: string
          type:
            - array
            - 'null'
        via:
          type: string
      required:
        - field
        - operator
      type: object
    RegulatoryFormatWire:
      additionalProperties: false
      properties:
        decimalSeparator:
          type: string
        groupSeparator:
          type: string
        pattern:
          type: string
        scale:
          format: int64
          type: integer
        scaleDeclared:
          type: boolean
        scaleIsExact:
          type: boolean
      required:
        - scaleDeclared
        - scaleIsExact
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: JWT bearer token issued by the identity provider.
      scheme: bearer
      type: http

````