openapi: 3.0.0
info:
  version: '5'
  title: Metadata API
  description: >
    A comprehensive suite of services that provides access to CDQ metadata. It
    is designed to offer basic services to  apply such a metadata, for instance,
    for parsing.
servers:
  - description: Production
    url: https://api.cdq.com/metadata/rest
    x-cdq-soap-url: https://api.corporate-data-league.ch/metadata/soap/v5
security:
  - apiKey: []
tags:
  - name: DataSources
    description: >-
      -> Categorize the API endpoints related to operations on data sources.
      These operations include reading data source metadata. The metadata
      provided includes data source names, data source technical keys, and data
      source categories.
paths:
  /v3/datasources:
    get:
      summary: List Data Source Metadata
      description: >
        Provides metadata on external data sources such as legal forms, address
        data, or legal entity data. Results are  paged by optional query
        parameters and filtered by additional parameters such as country short
        name or concepts  provided by the particular data source.
      tags:
        - DataSources
      parameters:
        - $ref: '#/components/parameters/countryShortNameOptional'
        - name: managedConceptTechnicalKey
          description: Technical key of a CDQ data model concept.
          in: query
          required: false
          schema:
            type: string
            example: LEGAL_FORM
        - name: aleiPrefix
          description: Prefix of the database name, according to ALEI standard.
          in: query
          required: false
          schema:
            type: string
            example: DE.RC
        - name: technicalKey
          description: Technical key.
          in: query
          required: false
          schema:
            type: string
            example: DE_RC
        - name: implementationStatus
          description: DEPRECATED, use 'releaseStatus' instead.
          in: query
          required: false
          schema:
            type: string
            example: ACTIVE
        - name: releaseStatus
          description: >
            See https://meta.cdq.com/Property:Release_status for semantics.
            According to CDLD-22386 list of 4,5,6,7,  corresponds to active data
            sources
          in: query
          required: false
          schema:
            type: array
            description: List of release statuses.
            items:
              type: integer
              description: 4,5,6,7, corresponds to active data sources.
              example: 4,5,6,7
        - name: primaryInCountry
          description: >
            ISO code of a country this data source is used in as a primary data
            source for compiling golden records.
          in: query
          required: false
          schema:
            type: string
            example: CH
        - name: preferredInCountry
          description: >
            ISO code of a country this data source is used in as a preferred
            data source for compiling golden records.
          in: query
          required: false
          schema:
            type: string
            example: CH
        - name: unallowedInCountry
          description: >
            ISO code of a country this data source is not allowed to be used in
            for compiling golden records.
          in: query
          required: false
          schema:
            type: string
            example: CH
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceMetadataPage'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
  schemas:
    IssuingBodyMetadata:
      type: object
      description: Metadata of an issuing body.
      properties:
        url:
          $ref: '#/components/schemas/IssuingBodyUrl'
        gleifCode:
          $ref: '#/components/schemas/IssuingBodyGleifCode'
        localAuthorityCode:
          $ref: '#/components/schemas/IssuingBodyLocalAuthorityCode'
        technicalKey:
          $ref: '#/components/schemas/IssuingBodyTechnicalKey'
        name:
          $ref: '#/components/schemas/IssuingBodyName'
        shortName:
          $ref: '#/components/schemas/IssuingBodyShortName'
        names:
          type: array
          description: List of the issuing body names.
          items:
            $ref: '#/components/schemas/Name'
        description:
          $ref: '#/components/schemas/IssuingBodyDescription'
        jurisdiction:
          $ref: '#/components/schemas/Jurisdiction'
        externalUrl:
          $ref: '#/components/schemas/IssuingBodyExternalUrl'
        identifierTypes:
          type: array
          description: List of identifier types issued by the body.
          items:
            $ref: '#/components/schemas/IdentifierType'
    IdentifierType:
      type: object
      description: Type of identifier.
      properties:
        technicalKey:
          $ref: '#/components/schemas/IdentifierTypeTechnicalKey'
    Country:
      type: object
      description: >-
        Country consisting of the country name and country code (ISO 3166-1
        alpha-2).
      properties:
        shortName:
          $ref: '#/components/schemas/CountryShortName'
    Jurisdiction:
      type: object
      description: >-
        The authority of an official organization to make decisions and
        judgments in a particular administrative area.
      required:
        - country
      properties:
        country:
          $ref: '#/components/schemas/Country'
        administrativeAreas:
          type: array
          description: List of administrative areas.
          items:
            $ref: '#/components/schemas/AdministrativeArea'
    AdministrativeArea:
      type: object
      description: A top-level geographical or political area division in a country.
      properties:
        value:
          $ref: '#/components/schemas/AdministrativeAreaValue'
        isoCode:
          $ref: '#/components/schemas/AdministrativeAreaIsoCode'
        shortName:
          $ref: '#/components/schemas/AdministrativeAreaShortName'
        type:
          $ref: '#/components/schemas/AdministrativeAreaType'
    AdministrativeAreaType:
      type: object
      description: Type of the Administrative Area.
      properties:
        technicalKey:
          $ref: '#/components/schemas/AdministrativeAreaTypeTechnicalKey'
    BusinessRule:
      type: object
      description: Set of information about the business rule.
      properties:
        name:
          $ref: '#/components/schemas/AdministrativeAreaValue'
        url:
          $ref: '#/components/schemas/BusinessRuleUrl'
        businessRuleType:
          type: string
          description: Type of the business rule.
          example: Data quality rule
        sparqlRule:
          type: string
          description: SPARQL rule.
          example: >-
            SELECT ?recordId 
              ?errorCode 
              ?content
              ?contentSelector
              ?contentSelectorUrl 
              ?parentConceptId 
              ?parentConceptIdSelector 
              ?parentConceptUrl 
            WHERE

            {
                ?businessPartner <http://meta.cdq.com/Property-3AHas_record_id> ?record_id ;
                    a <http://meta.cdq.com/BusinessPartner> .



            ?businessPartner
            <http://meta.cdq.com/Property-3ABusinessPartner/addresses> ?address.

            OPTIONAL { ?address
            <http://meta.cdq.com/Property-3ABusinessPartner/addresses/addressId>
            ?addrId . }

            ?address
            <http://meta.cdq.com/Property-3ABusinessPartner/addresses/country>
            ?country .

            ?address
            <http://meta.cdq.com/Property-3ABusinessPartner/addresses/postCodes>
            ?postCode .

                    OPTIONAL{?postCode <http://meta.cdq.com/Property-3ABusinessPartner/addresses/postCodes/value> ?value}
                    OPTIONAL{?postCode <http://meta.cdq.com/Property-3ABusinessPartner/addresses/postCodes/type> ?type .
                             ?type <http://meta.cdq.com/Property-3ABusinessPartner/addresses/postCodes/type/technicalKey> ?typeKey . }  
                    FILTER(BOUND(?value) && str(?value) != "")

               

            ?country
            <http://meta.cdq.com/Property-3ABusinessPartner/addresses/country/shortName>
            ?countryCode .

            FILTER(str(?countryCode) = "MK")


            FILTER EXISTS {

            ?xxx <http://meta.cdq.com/Property-3AHas_regular_expression> ?regexp
            .

            FILTER (?xxx IN (

            <http://meta.cdq.com/Regular_expression/Single_digit_post_code>,
            <http://meta.cdq.com/Regular_expression/Ordinal_sequence_of_numbers>,
            <http://meta.cdq.com/Regular_expression/One_digit_multiplied_several_times_post_code>,
            <http://meta.cdq.com/Regular_expression/Very_long_digits_post_code>,
            <http://meta.cdq.com/Regular_expression/Not_available_post_code>,
            <http://meta.cdq.com/Regular_expression/Mononumerical_post_code_with_delimeter>,
            <http://meta.cdq.com/Regular_expression/Only_special_characters>,
            <http://meta.cdq.com/Regular_expression/Only_alphabetic_characters>

            ))




            FILTER ( regex(str(?value), str(?regexp)) )

            }





              BIND(?record_id AS ?recordId)
              BIND ("200" AS ?errorCode)

              BIND ("" AS  ?parentConceptId)
              BIND ("" AS ?parentConceptIdSelector)
              BIND ("" AS ?parentConceptUrl)

              BIND (?value AS  ?content)
              BIND ("" AS  ?contentSelector)
              BIND ("" AS  ?contentSelectorUrl)
            }
        ruleStatus:
          type: string
          description: Status of the rule.
          example: RELEASED
        violationLevel:
          $ref: '#/components/schemas/ViolationLevel'
        violationMessage:
          type: string
          description: Violation message that is returned with detected data defect.
          example: >-
            City deviates from the reference city registered with the European
            value added tax identifier (Poland)
        qualificationTarget:
          type: string
          description: Qualification target.
          example: CITY
        description:
          type: string
          description: Description of the business rule.
          example: This rule checks if the business partner identifier is mandatory.
        primaryDataSource:
          $ref: '#/components/schemas/BusinessRuleDataSource'
        secondaryDataSource:
          $ref: '#/components/schemas/BusinessRuleDataSource'
        categories:
          type: array
          description: List of categories.
          items:
            $ref: '#/components/schemas/Category'
        managedIdentifiers:
          type: array
          description: List of managed identifiers.
          items:
            $ref: '#/components/schemas/ManagedIdentifier'
        countryShortName:
          type: string
          description: Country code.
          example: PL
        releaseDate:
          type: string
          description: >-
            Release date in ISO-8601 format. Each released rule is marked with
            release date. If the rule has DEACTIVATED status now, then this
            indicates the last release date before it was deactivated.
          example: '2025-08-29T09:47:02Z'
    BusinessRuleDataSource:
      type: object
      description: Data source of the business rule.
      properties:
        url:
          $ref: '#/components/schemas/DataSourceUrl'
        aleiPrefix:
          type: string
          description: Prefix of an external data source.
          example: VIES
    DataSourceUrl:
      type: string
      description: URL of the data source.
      example: https://ec.europa.eu/taxation_customs/vies/
    KnowledgeGraph:
      type: object
      description: Knowledge graph metadata.
      properties:
        id:
          type: string
          description: Knowledge graph ID.
          example: cdl
        baseUrl:
          type: string
          description: Base URL.
          example: https://meta.cdq.com
        wikiUrl:
          type: string
          description: Wiki URL.
          example: https://meta.cdq.com
        rdficationRootPrefix:
          type: string
          description: RDFication root prefix.
          example: Record
        dataMappingDefinitionId:
          type: string
          description: Data mapping definition ID.
          example: 678dgh4j2s834a37s74744784
        rootConcept:
          $ref: '#/components/schemas/Concept'
        sandboxMirrorId:
          type: string
          description: Sandbox mirror ID.
          example: 0015b56f17be0d0a955ea900b7d50346
        productionMirrorId:
          type: string
          description: Production mirror ID.
          example: 0015b00f17be3d0a955ea070b7d50346
    ViolationLevel:
      type: string
      description: >-
        -> Indicates the criticality of the applied rule. If a data defect is
        found, then the user will get `INFO`, `WARNING` or `ERROR` level.
        Otherwise, it will be NO_DEFECT.
      example: ERROR
    BusinessRuleUrl:
      type: string
      description: Represents Data Quality Rule url.
      example: >-
        https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))
    Criticality:
      type: object
      description: Criticality of the business rule.
      properties:
        buisnessRuleUrl:
          $ref: '#/components/schemas/BusinessRuleUrl'
        violationLevel:
          $ref: '#/components/schemas/ViolationLevel'
    Concept:
      type: object
      description: Concept for RDFication.
      properties:
        idSelector:
          type: string
          description: ID selector.
          example: /partner/header/objectInstance/bpartner
        name:
          type: string
          description: Name of the concept.
          example: bpartner
    Category:
      type: object
      description: Category of the business rule.
      properties:
        url:
          $ref: '#/components/schemas/ValidationRuleCategoryUrl'
        name:
          type: string
          description: Name of the category.
          example: Data Quality
    ManagedIdentifier:
      type: object
      description: Managed identifier.
      properties:
        technicalKey:
          $ref: '#/components/schemas/IdentifierTypeTechnicalKey'
    SapIdentifierMapping:
      type: object
      description: Mapping of SAP identifier.
      properties:
        country:
          $ref: '#/components/schemas/Country'
        sapIdentifierType:
          $ref: '#/components/schemas/SapIdentifierType'
        identifierType:
          $ref: '#/components/schemas/IdentifierType'
    SapIdentifierType:
      type: object
      description: Type of SAP identifier.
      properties:
        technicalKey:
          type: string
          description: Technical key of the SAP identifier type.
          example: STCD1
    SapCdlIdentifierMappingTermItem:
      type: object
      description: Term item for SAP identifier mapping.
      required:
        - countryShortName
        - cdlIdentifierTypeTechnicalKey
      properties:
        countryShortName:
          type: string
          description: Country code.
          example: DE
        cdlIdentifierTypeTechnicalKey:
          type: string
          description: CDL identifier type technical key.
          example: cdl
    DataModelValueMapping:
      type: object
      description: Mapping from values of external data models to values of CDQ Data Model.
      properties:
        url:
          type: string
          description: URL of the data model value mapping.
          example: >-
            https://meta.cdq.com/Data_source/LEI/data_model/LEI_Data_Record/entity/legalForm/entityLegalFormCode/106J/mapping/CDQ
        dataSourcePrefix:
          type: string
          description: ALEI a prefix of the database the data model values come from.
          example: LEI
        sourceValue:
          type: string
          description: The effective value which is mapped.
          example: 106J
        sourceParentConceptPath:
          type: string
          description: The data model concept the value is provided by.
          example: entity.legalForm.entityLegalFormCode
        targetValue:
          type: string
          description: >-
            The effective value of the CDQ Data Model the source value is mapped
            to.
          example: BY_1985
        targetParentConceptPath:
          type: string
          description: CDQ Data Model concept the target value is provided by.
          example: legalForm
    CountryMetadata:
      type: object
      description: Metadata for a specific country.
      properties:
        url:
          type: string
          description: URL of the country metadata.
          example: https://meta.cdq.com/Category:Country
        countryShortName:
          $ref: '#/components/schemas/CountryShortName'
        continent:
          type: object
          description: The continent the country belongs to.
          example: Europe
        officialTerms:
          type: array
          description: List of official terms for the country.
          items:
            $ref: '#/components/schemas/TermMetadata'
        alternativeTerms:
          type: array
          description: List of alternative terms for the country.
          items:
            $ref: '#/components/schemas/TermMetadata'
        shortNames:
          type: array
          description: List of short names for the country.
          items:
            $ref: '#/components/schemas/TermMetadata'
        shortNationalities:
          type: array
          description: List of short nationalities for the country.
          items:
            $ref: '#/components/schemas/TermMetadata'
        nationalities:
          type: array
          description: List of nationalities for the country.
          items:
            $ref: '#/components/schemas/TermMetadata'
        languages:
          type: array
          description: List of languages spoken in the country.
          items:
            $ref: '#/components/schemas/LanguageName'
    DataSourceMetadataPage:
      type: object
      description: Page of data source metadata.
      properties:
        pageSize:
          $ref: '#/components/schemas/PageSize'
        page:
          $ref: '#/components/schemas/Page'
        total:
          $ref: '#/components/schemas/Total'
        values:
          type: array
          description: List of data source metadata.
          items:
            $ref: '#/components/schemas/DataSourceMetadata'
    DataSourceGoldenRecord:
      type: object
      description: Data source for golden record.
      properties:
        url:
          type: string
          description: URL of the data source.
          example: https://ec.europa.eu/taxation_customs/vies/
        aleiPrefix:
          type: string
          description: Prefix of the database name, according to ALEI standard.
          example: VIES
        technicalKey:
          type: string
          description: Technical key of the data source.
          example: VIES
        shortName:
          type: string
          description: Short name of the data source.
          example: VIES
        releaseStatus:
          type: integer
          description: |
            See https://meta.cdq.com/Property:Release_status for semantics.
          example: '1'
    DataSourceAccessData:
      type: object
      description: Access data for a data source.
      properties:
        url:
          type: string
          description: URL of the data source.
          example: https://meta.cdq.com/Data_source/VIES
        aleiPrefix:
          type: string
          description: Prefix of the database name, according to ALEI standard.
          example: VIES
        technicalKey:
          type: string
          description: Technical key of the data source.
          example: VIES
        termsType:
          type: string
          description: Type of terms for the data source.
          example: EU_PUBLIC
        releaseStatus:
          type: integer
          description: |
            See https://meta.cdq.com/Property:Release_status for semantics.
          example: '1'
        category:
          type: string
          description: Category of the data source.
          example: BUSINESS_PARTNER
        licenceUrl:
          type: string
          description: >
            URL that provides information on the license of the target see
            https://meta.cdq.com/Property:Has_licence_URL
          example: https://eur-lex.europa.eu/eli/dec/2011/833/oj
        credentials:
          type: array
          description: List of credential types.
          items:
            $ref: '#/components/schemas/CredentialType'
        countries:
          type: array
          description: List of country short names.
          items:
            type: string
            description: Country short name.
            example: CH
        fullName:
          $ref: '#/components/schemas/FullName'
    FullName:
      type: string
      description: English name of a concept.
      example: VAT Information Exchange System
    CredentialType:
      type: object
      description: Type of single credential value.
      properties:
        technicalKey:
          type: string
          description: Technical key of the credential type.
          example: AT_FON_CREDENTIALS
        label:
          type: string
          description: Label of the credential type.
          example: European VAT identifier (Austria)
        description:
          type: string
          description: Description of the credential type.
          example: These are the mandatory credentials for AT.FON
        credentials:
          type: array
          description: List of credentials.
          items:
            $ref: '#/components/schemas/Credential'
    Credential:
      type: object
      description: Single credential value.
      properties:
        technicalKey:
          type: string
          description: Technical key of the credential.
          example: EU_VAT_ID_AT
        description:
          type: string
          description: Description of the credential.
          example: Requestor Credentials
        label:
          type: string
          description: Label of the credential.
          example: AT VAT number
        fieldType:
          type: string
          description: >
            Define what type of information is provided with that filed.
            Password or Text.
          example: Text
    DataSourceMetadata:
      type: object
      description: Metadata for a specific data source.
      properties:
        url:
          type: string
          description: URL of the data source.
          example: https://meta.cdq.com/Data_source/VIES
        aleiPrefix:
          type: string
          description: Prefix of the database name, according to ALEI standard.
          example: VIES
        technicalKey:
          type: string
          description: Technical key of the data source.
          example: VIES
        shortName:
          type: string
          description: Short name of the data source.
          example: VIES
        fullName:
          $ref: '#/components/schemas/FullName'
        localName:
          type: string
          description: Local name of the data source.
          example: VAT Information Exchange System
        shortDescription:
          type: string
          description: Short description of the data source.
          example: Official interface to the European MIAS database.
        businessRegistryCode:
          type: string
          description: Business registry code of the data source.
          example: RA000274
        countryScope:
          type: string
          description: DEPRECATED, please use 'countryScopeList' instead.
          example: CH
          items:
            type: string
            description: Country short name.
            example: CH
        countryScopeList:
          type: array
          description: List of country short names.
          items:
            type: string
            description: Country short name.
            example: CH
        managedConceptTechnicalKeys:
          type: array
          description: List of managed concept technical keys.
          items:
            $ref: '#/components/schemas/ConceptTechnicalKey'
        managedIdentifierTypes:
          type: array
          description: List of managed identifier types.
          items:
            $ref: '#/components/schemas/IdentifierTypeTechnicalKey'
        categories:
          type: array
          description: List of categories.
          items:
            type: string
            description: Category of the data source.
            example: VAT
        implementationStatus:
          type: string
          description: DEPRECATED, please use 'releaseStatus' instead.
          example: N/A
        releaseStatus:
          type: integer
          description: https://meta.cdq.com/Property:Release_status for semantics.
          example: '1'
        dataOwnership:
          type: string
          description: Data ownership of the data source.
          example: GOVERNMENTAL
        dataProvision:
          type: string
          description: The data provision of the data source.
          example: OPEN
        termsType:
          type: string
          description: Type of terms for the data source.
          example: EU_PUBLIC
        numberOfRecords:
          type: integer
          description: >
            Count the number of company records available in the data source,
            see https://meta.cdq.com/Property:Has_number_of_records
          example: '50000000'
        provider:
          type: string
          description: >
            Provider or authority of a data source, see
            https://meta.cdq.com/Property:Has_provider
          example: European Commission
        licenceUrl:
          type: string
          description: >
            URL that provides information on the license of the target see
            https://meta.cdq.com/Property:Has_licence_URL
          example: https://eur-lex.europa.eu/eli/dec/2011/833/oj
        credentialTypes:
          type: array
          description: >
            List of credential types, by their technical keys, see Type of
            single credential value.

            Possible values:  * `API_KEY` * `DUNS` * `EU_VAT_ID_AT` *
            `EU_VAT_ID_DE` * `PASSWORD` * `TEILNEHMER_ID` * `USERNAME`
          items:
            type: string
            description: Credential type.
            example: USERNAME
    IdentifierMetadata:
      type: object
      description: Metadata for a specific identifier.
      properties:
        url:
          type: string
          description: URL of the identifier.
          example: https://meta.cdq.com/Business_partner/identifier/type
        countryScope:
          type: string
          description: Country scope of the identifier.
          example: CH
        name:
          type: string
          description: Name of the identifier.
          example: VAT ID
        technicalKey:
          type: string
          description: Technical key of the identifier.
          example: VAT_ID
        sapDefaultMapping:
          type: string
          description: SAP default mapping of the identifier.
          example: STCD2
        sapTaxCategory:
          type: string
          description: SAP tax category of the identifier.
          example: STCD1
        categories:
          type: array
          description: List of categories.
          items:
            type: string
            description: Category of the identifier.
            example: Tax Number
        officialNames:
          type: array
          description: List of official names.
          items:
            $ref: '#/components/schemas/TermMetadata'
        shortNames:
          type: array
          description: List of short names.
          items:
            $ref: '#/components/schemas/TermMetadata'
    LegalFormMetadata:
      type: object
      description: Metadata for a specific legal form.
      properties:
        url:
          type: string
          description: URL of the legal form.
          example: https://meta.cdq.com/Business_partner/legal_form
        name:
          type: string
          description: Name of the legal form.
          example: Aktiengesellschaft
        technicalKey:
          type: string
          description: Technical key of the legal form.
          example: AE_2507
        language:
          $ref: '#/components/schemas/Language'
        countryScope:
          type: string
          description: Country scope of the legal form.
          example: CH
        mainAbbreviation:
          type: string
          description: Main abbreviation of the legal form.
          example: AG
        abbreviations:
          type: array
          description: List of abbreviations.
          items:
            type: string
            description: Abbreviation of the legal form.
            example: Aktienges.
        defectiveAbbreviations:
          type: array
          description: List of defective abbreviations.
          items:
            type: string
            description: Defective abbreviation of the legal form.
            example: AktionG
        internationalName:
          type: string
          description: International name of the legal form.
          example: Public Limited Company
        categories:
          type: array
          description: List of categories.
          items:
            $ref: '#/components/schemas/LegalFormCategory'
    LegalFormCategory:
      type: object
      description: The categorization of a Legal Form.
      properties:
        technicalKey:
          $ref: '#/components/schemas/LegalFormCategoryTechnicalKey'
        name:
          $ref: '#/components/schemas/LegalFormCategoryName'
        shortName:
          $ref: '#/components/schemas/LegalFormCategoryShortName'
        url:
          $ref: '#/components/schemas/LegalFormCategoryUrl'
    LegalFormCategoryMetadata:
      type: object
      description: Metadata for a specific legal form category.
      properties:
        technicalKey:
          $ref: '#/components/schemas/LegalFormCategoryTechnicalKey'
        name:
          $ref: '#/components/schemas/LegalFormCategoryName'
        shortName:
          $ref: '#/components/schemas/LegalFormCategoryShortName'
        description:
          type: string
          description: Description of the legal form category.
          example: Public limited company
        url:
          $ref: '#/components/schemas/LegalFormCategoryUrl'
    RegionMetadata:
      type: object
      description: Metadata for a specific region.
      properties:
        url:
          type: string
          description: URL of the region.
          example: https://meta.cdq.com/Address/administrative_area/type/region/CH-AG
        countryShortName:
          type: string
          description: Country short name.
          example: CH
        regionShortName:
          type: string
          description: Region short name.
          example: CH-AG
        sapDefaultMapping:
          type: string
          description: SAP default mapping of the region.
          example: AG
        fipsCode:
          $ref: '#/components/schemas/FipsCode'
        regionTerms:
          type: array
          description: List of region terms.
          items:
            $ref: '#/components/schemas/TermMetadata'
        officialNames:
          type: array
          items:
            $ref: '#/components/schemas/TermMetadata'
        shortNames:
          type: array
          description: List of short names.
          items:
            $ref: '#/components/schemas/TermMetadata'
        alternativeNames:
          type: array
          description: List of alternative names.
          items:
            $ref: '#/components/schemas/TermMetadata'
    CountyRegionMetadata:
      type: object
      description: Metadata for a specific region.
      properties:
        url:
          type: string
          description: URL of the region.
          example: >-
            https://meta.cdq.com/Address/administrative_area/type/county/US-CO/8089
        regionShortName:
          type: string
          description: Region short name.
          example: US-CO
        regionTerms:
          type: array
          description: List of region terms.
          items:
            $ref: '#/components/schemas/TermMetadata'
    CountyMetadata:
      type: object
      description: Metadata for a specific county.
      properties:
        url:
          type: string
          description: URL of the county.
          example: https://meta.cdq.com/Address/administrative_area/type/county
        fipsCode:
          $ref: '#/components/schemas/FipsCode'
        countyTerms:
          type: array
          description: List of county terms.
          items:
            $ref: '#/components/schemas/TermMetadata'
        countryShortName:
          type: string
          description: Country short name.
          example: US
        regionShortName:
          type: string
          description: Region short name.
          example: US-CO
        countyShortName:
          type: string
          description: County short name.
          example: US
        region:
          $ref: '#/components/schemas/CountyRegionMetadata'
    FipsCode:
      type: object
      description: >-
        FIPS codes are numbers that uniquely identify geographic areas. The
        number of digits in FIPS codes varies depending on the level of
        geography. State-level FIPS codes have two digits, county-level FIPS
        codes have five digits of which the first two are the FIPS code of the
        state to which the county belongs.
      properties:
        value:
          type: string
          description: FIPS code.
          example: SZ15
    PostalDeliveryPointMatch:
      type: object
      description: Matched postal delivery point.
      properties:
        term:
          $ref: '#/components/schemas/TermMetadataContainer'
        matchedString:
          type: string
          description: Detected Postal Delivery Point in input.
          example: BP 8307
        matchedNumber:
          type: string
          description: Detected Postal Delivery Point number in input.
          example: '8307'
    PremiseMatch:
      type: object
      description: Matched premise.
      properties:
        term:
          $ref: '#/components/schemas/TermMetadataContainer'
        matchedString:
          type: string
          description: Detected Premise in input.
          example: 6, rue Alfred Kastler BP 8307
        matchedNumber:
          type: string
          description: Detected Premise number in input.
          example: '6'
        matchPositionStart:
          type: integer
          description: Start of the found Premise with number.
          example: '0'
        matchPositionEnd:
          type: integer
          description: End of the found Premise with number.
          example: '1'
        premiseOnly:
          type: boolean
          description: Detected Premise with Number is the only content of an input.
          example: 'true'
        startsWithPremise:
          type: boolean
          description: Match is placed at the beginning of an input.
          example: 'true'
        matchedAbbreviation:
          type: boolean
          description: The match is an abbreviation.
          example: 'true'
    TermMetadataContainer:
      type: object
      description: Container for term metadata.
      properties:
        countryScope:
          type: string
          description: Country scope of the term.
          default: WORLD
          example: CH
        term:
          $ref: '#/components/schemas/TermMetadata'
        officialTerm:
          $ref: '#/components/schemas/TermMetadata'
        alternativeTerms:
          type: array
          description: List of alternative terms.
          items:
            $ref: '#/components/schemas/TermMetadata'
        mainAbbreviation:
          $ref: '#/components/schemas/TermMetadata'
        officialAbbreviation:
          $ref: '#/components/schemas/TermMetadata'
        alternativeAbbreviations:
          type: array
          description: List of alternative abbreviations.
          items:
            $ref: '#/components/schemas/TermMetadata'
        positions:
          type: array
          description: List of positions.
          items:
            type: string
            description: Position of the term.
            example: SUFFIX
        conceptTypeTechnicalKey:
          $ref: '#/components/schemas/ConceptTechnicalKey'
    TermMetadata:
      type: object
      description: Metadata for a specific term.
      properties:
        value:
          type: string
          description: Value of the term.
          example: Strasse
        languageTechnicalKey:
          type: string
          description: Language technical key.
          default: en
          example: de
    EndpointMetadata:
      type: object
      description: Metadata for a specific endpoint.
      properties:
        url:
          type: string
          description: URL of the endpoint.
          example: >-
            https://developer.cdq.com/reference-docs/metadata/V3/#tag/DataSources/paths/~1v3~1datasources/get
        name:
          type: string
          description: Name of the endpoint.
          example: Read Data Source Metadata
        technicalKey:
          type: string
          description: Technical key of the endpoint.
          example: Technical_Key
        shortDescription:
          type: string
          description: Short description of the endpoint.
          example: Read data source metadata.
        description:
          type: string
          description: Description of the endpoint.
          example: >-
            Provides metadata on external data sources such as legal forms,
            address data, or legal entity data.
        useCases:
          type: array
          description: List of use cases.
          items:
            $ref: '#/components/schemas/UseCaseMetadata'
    UseCaseMetadata:
      type: object
      description: Metadata for a specific use case.
      properties:
        url:
          type: string
          description: URL of the use case.
          example: https://meta.cdq.com/Category:Use_case
        name:
          type: string
          description: Name of the use case.
          example: Address Cleansing
        shortDescription:
          type: string
          description: Short description of the use case.
          example: Cleanse address data.
        description:
          type: string
          description: Description of the use case.
          example: Cleanse address data by normalizing and validating address data.
        productFeatures:
          type: array
          description: List of product features.
          items:
            $ref: '#/components/schemas/ProductFeatureMetadata'
    ProductFeatureMetadata:
      type: object
      description: Metadata for a specific product feature.
      properties:
        url:
          type: string
          description: URL of the product feature.
          example: https://meta.cdq.com/Category:Product_feature
        name:
          type: string
          description: Name of the product feature.
          example: Address Cleansing and Enrichment
        shortDescription:
          type: string
          description: Short description of the product feature.
          example: Cleanse and enrich address data.
        description:
          type: string
          description: Description of the product feature.
          example: >-
            Cleanse and enrich address data by normalizing and validating
            address data.
        featureContext:
          type: string
          description: Context of the product feature.
          example: Address
    ConceptMetadata:
      type: object
      description: Metadata for a specific concept.
      properties:
        url:
          type: string
          description: URL of the concept.
          example: https://meta.cdq.com/Category:Data_model_concept
        name:
          type: string
          description: Name of the concept.
          example: Address
        technicalKey:
          type: string
          description: Technical key of the concept.
          example: ADDRESS
        parentConceptTechnicalKey:
          type: string
          description: Technical key of the parent concept.
          example: BUSINESS_PARTNER
        description:
          type: string
          description: Description of the concept.
          example: Address data.
    Page:
      type: integer
      description: >-
        < The number of the page, as specified in the request, or '0' as
        default.
      example: '1'
    PageSize:
      type: integer
      description: >-
        < The size of the provided page, as specified in the request, or by the
        default value.
      example: '10'
    Total:
      type: integer
      description: < Total number of elements across all pages.
      example: '100'
    RegexMetadata:
      type: object
      description: Metadata for a specific regex.
      properties:
        url:
          type: string
          description: URL of the regex.
          example: https://meta.cdq.com/Regular_expression/ABN_AU/format
        name:
          type: string
          description: Name of the regex.
          example: Regular expression/ABN AU/format
        regex:
          type: string
          description: Regex pattern.
          example: ^(\s*?\.*?-*?)(\d\s*\.*-*){11}$
        regexType:
          $ref: '#/components/schemas/RegexType'
        countryShortName:
          type: string
          description: Country short name.
          example: CH
        managedConcepts:
          type: array
          description: List of managed concepts.
          items:
            $ref: '#/components/schemas/ConceptMetadata'
    RegexType:
      type: object
      description: Type of regex.
      properties:
        name:
          type: string
          description: Name of the regex type.
          example: Legal form pattern
    StatementObject:
      type: object
      description: Object of a statement.
      properties:
        url:
          type: string
          description: URL of the statement.
          example: https://meta.cdq.com/Data_Sharing
        value:
          type: string
          description: Value of the statement.
          example: Data_Sharing
        type:
          type: string
          description: Type of the statement.
          example: CONCEPT
    Language:
      type: object
      description: Naming of a language according to ISO 639-1.
      properties:
        technicalKey:
          $ref: '#/components/schemas/LanguageTechnicalKey'
    LinkageStrategyMetadata:
      type: object
      description: Metadata for a specific linkage strategy.
      properties:
        dataSourcePrefix:
          deprecated: true
          type: string
          description: Prefix of the data source.
          example: LEI
        countryCode:
          type: string
          description: Country code.
          example: CH
        releaseStatus:
          type: string
          description: Release status of the linkage strategy.
          example: RELEASED
        linkageMatchingConfiguration:
          type: string
          description: Matching configuration of the linkage strategy.
          example: SIMILARITY
        similarityMatchingConfiguration:
          type: string
          description: Matching configuration of the linkage strategy.
          example: SIMILARITY
        similarityMatchThreshold:
          type: string
          description: Match the threshold of the linkage strategy.
          example: '0.8'
        similarityMaybeMatchThreshold:
          type: string
          description: Maybe match the threshold of the linkage strategy.
          example: '0.6'
        dataSource:
          $ref: '#/components/schemas/LinkageStrategyMetadataDataSource'
    LinkageStrategyMetadataDataSource:
      type: object
      description: Metadata for a specific linkage strategy data source.
      properties:
        aleiPrefix:
          type: string
          description: Prefix of the ALEI.
          example: LEI
        technicalKey:
          type: string
          description: Technical key of the data source.
          example: LEI
    ReleaseNoteSearchResult:
      type: object
      description: Search result of a release note.
      properties:
        date:
          type: string
          description: Date when release note was released.
          example: '2025-08-29T09:47:02Z'
        url:
          type: string
          description: Metadata url to release note.
          example: https://meta.cdq.com/Release_note
        headline:
          type: string
          description: Summary of a release note.
          example: CLIENT
        description:
          type: string
          description: Description of a release.
          example: CLIENT
    ServiceQuotaMetadata:
      type: object
      description: Metadata for a specific service quota.
      properties:
        serviceTechnicalKey:
          type: string
          description: >-
            Technical Key to identify an internal or external service used in
            the CDQ Cloud Services.
          example: CH_UIDR
        maxAmount:
          type: integer
          format: int64
          description: Defines the amount of the quota.
          example: '20000'
        reset:
          type: string
          description: Defines who is able to maintain this quota.
          example: CLIENT
        control:
          type: string
          description: Defines who is able to maintain this quota.
          example: CLIENT
    SanctionListIssuingBody:
      type: object
      description: Issuing body of a sanction list.
      properties:
        technicalKey:
          type: string
          description: Technical key of the issuing body.
          example: INFO4C_WL_ISSUER_59
        name:
          type: string
          description: Name of the issuing body.
          example: >-
            US Department of the Treasury, Office of Foreign Assets Control
            (OFAC)
        lists:
          type: array
          description: List of sanction lists.
          items:
            $ref: '#/components/schemas/SanctionList'
    SanctionList:
      type: object
      description: Sanction list.
      properties:
        technicalKey:
          type: string
          description: Technical key of the sanction list.
          example: INFO4C_WL_224
        name:
          type: string
          description: Name of the sanction list.
          example: Civil Penalties and Enforcement Information
    WatchListIssuingBody:
      type: object
      description: Issuing body of a watch list.
      properties:
        technicalKey:
          type: string
          description: Technical key of the issuing body.
          example: INFO4C_WL_ISSUER_112
        name:
          type: string
          description: Name of the issuing body.
          example: Interpol
        lists:
          type: array
          description: List of watch lists.
          items:
            $ref: '#/components/schemas/WatchList'
    WatchList:
      type: object
      description: Watch list.
      properties:
        technicalKey:
          type: string
          description: Technical key of the watch list.
          example: INFO4C_WL_31
        name:
          type: string
          description: Name of the watch list.
          example: Interpol-Wanted List
    PEPList:
      type: object
      description: PEP list.
      properties:
        technicalKey:
          type: string
          description: Technical key of the PEP list.
          example: INFO4C_PEP_15
        country:
          type: string
          description: Country of the PEP list.
          example: European Union
    IssuingBodyUrl:
      description: >-
        URL to the documentation which summarizes all details of a [Issuing
        Body](https://meta.cdq.com/Business_partner/identifier/issuing_body).
      example: https://meta.cdq.com/Business_partner/identifier/issuing_body
      type: string
    IssuingBodyGleifCode:
      type: string
      description: Code of Global Legal Entity Identifier Foundation (GLEIF)
      example: RA000004
    IssuingBodyLocalAuthorityCode:
      type: string
      description: Code of the local registration authority
      example: R3101
    IssuingBodyTechnicalKey:
      description: Technical key of the Issuing Body.
      example: Amtsgericht Aachen
      type: string
    IssuingBodyName:
      type: string
      description: Preferred display label for an Issuing Body.
      example: Amtsgericht Aachen
    IssuingBodyShortName:
      type: string
      description: Preferred short display label for an Issuing Body.
      maxLength: 50
      example: Amtsgericht Aachen
    NameShortName:
      type: string
      description: The abbreviated variant of a company's full name.
      example: CDQ AG
    NameTypeUrl:
      type: string
      description: >-
        URL to the documentation which summarizes all details of the [Name
        Type](https://meta.cdq.com/Business_partner/name/type).
      example: https://meta.cdq.com/Business_partner/name/type
    NameTypeName:
      type: string
      description: Display label for the Name Type.
      example: Local Name
    NameTypeTechnicalKey:
      type: string
      description: Technical Keys of the Name Type.
      example: LOCAL
    NameType:
      type: object
      description: >-
        The type of the name, e.g. a locally used name or an international
        version.
      properties:
        url:
          $ref: '#/components/schemas/NameTypeUrl'
        name:
          $ref: '#/components/schemas/NameTypeName'
        technicalKey:
          $ref: '#/components/schemas/NameTypeTechnicalKey'
    NameValue:
      type: string
      description: The actual name.
      example: Corporate Data Quality AG
    LanguageName:
      type: string
      description: ISO 639-1 name of language.
      example: German
    LanguageTechnicalKey:
      type: string
      description: ISO 639-1 two-letter code of languages.
      example: DE
    schemas-Language:
      type: object
      description: Naming of a language according to ISO 639-1.
      properties:
        name:
          $ref: '#/components/schemas/LanguageName'
        technicalKey:
          $ref: '#/components/schemas/LanguageTechnicalKey'
    Name:
      type: object
      description: The name of a business partner.
      properties:
        shortName:
          $ref: '#/components/schemas/NameShortName'
        type:
          $ref: '#/components/schemas/NameType'
        value:
          $ref: '#/components/schemas/NameValue'
        language:
          $ref: '#/components/schemas/schemas-Language'
    IssuingBodyDescription:
      type: string
      description: Description for an Issuing Body.
      example: Amtsgericht Aachen
    CountryShortName:
      type: string
      description: Country code (ISO 3166-1 alpha-2).
      example: CH
    AdministrativeAreaValue:
      type: string
      description: >-
        Name of the [Administrative
        Area](https://meta.cdq.com/Address/administrative_area).
      example: Sankt Gallen
    AdministrativeAreaIsoCode:
      type: string
      description: >-
        ISO 3166-2 code which uniquely defines the names of countries and their
        subdivisions (e.g., provinces or states).
      example: CH-SG
    AdministrativeAreaShortName:
      type: string
      description: >-
        Abbreviation for the [Administrative
        Area](https://meta.cdq.com/Address/administrative_area).
      example: SG
    AdministrativeAreaTypeTechnicalKey:
      type: string
      description: Technical key of the Administrative Area.
      example: COUNTY
    IssuingBodyExternalUrl:
      type: string
      description: External url of the issuing body
      example: https://www.amtsgericht.de/muenchen
    IdentifierTypeTechnicalKey:
      type: string
      description: Technical key of the type of the Identifier.
      example: CH_VAT_ID
    ValidationRuleCategoryUrl:
      type: string
      description: Used to filter rule by its URL.
      example: https://meta.cdq.com/Qualification
    ConceptTechnicalKey:
      type: string
      description: Technical key of the Concept.
      example: ADDRESS
    LegalFormCategoryTechnicalKey:
      type: string
      description: >-
        Technical Key of the [Legal Form
        Category](https://meta.cdq.com/Business_partner/legal_form/category).
      example: LIMITED
    LegalFormCategoryName:
      type: string
      maxLength: 40
      description: Descriptive display name of the Legal Form Category.
      example: Limited Liability Company
    LegalFormCategoryShortName:
      type: string
      maxLength: 15
      description: Short display name of the Legal Form Category.
      example: LLC
    LegalFormCategoryUrl:
      type: string
      description: >-
        URL to the documentation which summarizes all details of the [Legal Form
        Category](https://meta.cdq.com/Business_partner/legal_form/category).
      example: >-
        https://meta.cdq.com/Business_partner/legal_form/category/technical_key/LF001
    CharacterSetName:
      type: string
      description: >-
        Name of character set. Supported character sets can be found
        [here](https://meta.cdq.com/Address/version/character_set).
      example: International
    CharacterSetTechnicalKey:
      type: string
      description: >-
        Technical key of character set. Supported character sets can be found
        [here](https://meta.cdq.com/Address/version/character_set).
      example: INTERNATIONAL
    CharacterSet:
      type: object
      description: Character set.
      properties:
        name:
          $ref: '#/components/schemas/CharacterSetName'
        technicalKey:
          $ref: '#/components/schemas/CharacterSetTechnicalKey'
    ApiErrorTimestamp:
      type: string
      deprecated: true
      description: ISO 8601 representation of the timestamp.
      example: '2025-08-29T09:47:02Z'
    ApiErrorMessage:
      type: string
      deprecated: true
      description: Details about the error.
      example: This user is not allowed to access this service.
    HttpError:
      type: string
      description: RFC 7231 error which belongs to the status code.
      example: BAD_REQUEST
      deprecated: true
    HttpPath:
      type: string
      description: Requested path which caused this error.
      example: /v2/businesspartners/lookup
    HttpStatus:
      type: integer
      description: RFC 7231 status code for this error.
      example: '400'
      deprecated: true
  parameters:
    page:
      name: page
      description: The number of the page to read, starting with '0'.
      in: query
      required: false
      schema:
        type: integer
        default: 0
        example: '1'
    pageSize:
      name: pageSize
      description: Maximum number of elements on the page to read.
      in: query
      required: false
      schema:
        type: integer
        default: 10
        example: '10'
    countryShortNameMandatory:
      name: countryShortName
      description: Country short name, i.e., the 2-digit ISO code.
      in: query
      required: true
      schema:
        type: string
        example: CH
    countryShortNameOptional:
      name: countryShortName
      description: Country short name, i.e., the 2-digit ISO code.
      in: query
      required: false
      schema:
        type: string
        example: CH
