Emporix Custom Schema Type API

openapi: 3.2.0
info:
  title: Emporix Custom Schema Type API
  version: ''
  contact:
    email: documentation@emporix.com
  description: 'Operations tagged Custom Schema Type across 2 of this provider''s published API definitions: emporix-schema-openapi.yml, emporix-schema-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
security:
- OAuth2: []
tags:
- name: Custom Schema Type
paths:
  /schema/{tenant}/custom-entities:
    parameters:
    - $ref: '#/components/parameters/tenant'
    post:
      tags:
      - Custom Schema Type
      summary: Creating a custom schema type
      description: 'Creates a custom type entity that can be later used for creating custom instances.


        **Note**: When a custom entity type is created, a set of custom scopes is created, which allow managing custom instances of that type.


        Reserved built-in type IDs cannot be used as custom schema type IDs. This includes AVAILABILITY and LOCATION.'
      operationId: POST-schema-create-custom-schema-type
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomSchemaTypeCreation'
            example:
              id: CUSTOM_PRODUCT
              name:
                en: Custom Product Type
      responses:
        '201':
          description: The request was successful. Custom schema type has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdResponse'
              example:
                id: CUSTOM_PRODUCT
        '400':
          $ref: '#/components/responses/Bad_request_400_cl'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          description: Permission denied due to insufficient rights. This may happen when the request does not contain sufficient scopes for the given query values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Forbidden:
                  value:
                    code: 403
                    status: Forbidden
                    message: You need to choose the required scope to complete this action.
                    details:
                    - message: 'Required scope(s): schema.schema_manage'
        '409':
          $ref: '#/components/responses/Conflict_409'
      security:
      - OAuth2:
        - schema.schema_manage
      parameters:
      - $ref: '#/components/parameters/trait_contentLanguage_header'
    get:
      summary: Retrieving all custom schema types
      description: Retrieves all custom schema types.
      tags:
      - Custom Schema Type
      responses:
        '200':
          description: ''
          headers:
            X-Total-Count:
              description: Total amount of custom types for given criteria.
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomSchemaTypesResponse'
              example:
              - id: CUSTOM_PRODUCT
                name:
                  en: Custom Product Type
                metadata:
                  createdAt: '2023-08-09T09:21:42.693Z'
                  modifiedAt: '2023-08-09T09:21:42.693Z'
                  version: 1
              - id: DOCUMENT
                name:
                  en: Documents
                metadata:
                  createdAt: '2023-08-10T10:15:30.123Z'
                  modifiedAt: '2023-08-19T10:15:30.123Z'
                  version: 2
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
      operationId: GET-schema-retrieve-custom-schema-types
      parameters:
      - $ref: '#/components/parameters/trail_xTotalCount_header'
      - $ref: '#/components/parameters/trait_acceptLanguage_header'
      - $ref: '#/components/parameters/trait_paged_pageNumber'
      - $ref: '#/components/parameters/trait_paged_pageSize'
      - $ref: '#/components/parameters/trait_sort'
      - $ref: '#/components/parameters/trait_q_param'
      - $ref: '#/components/parameters/trait_fields'
      - $ref: '#/components/parameters/trait_expand_schemas'
    servers:
    - url: https://api.emporix.io
  /schema/{tenant}/custom-entities/{id}:
    parameters:
    - $ref: '#/components/parameters/tenant'
    - name: id
      in: path
      required: true
      schema:
        type: string
      description: Unique id of the custom type.
    get:
      summary: Retrieving a custom schema type
      description: Retrieves a single custom schema type by id.
      tags:
      - Custom Schema Type
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomSchemaTypeResponse'
              examples:
                CustomType:
                  $ref: '#/components/examples/CustomSchemaTypeResponse'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '404':
          $ref: '#/components/responses/Not_Found_404'
      operationId: GET-schema-retrieve-custom-schema-type
      parameters:
      - $ref: '#/components/parameters/trait_acceptLanguage_header'
      - $ref: '#/components/parameters/trait_expand_schemas'
    delete:
      summary: Deleting a custom schema type
      description: 'Deletes a single custom type. This operation will fail if there are schemas or custom instances assigned to this custom type.


        **Note**: Removing a custom entity type does not remove the custom scopes that were created when the type was added. Those scopes remain in the system until you remove them manually, if needed.'
      tags:
      - Custom Schema Type
      responses:
        '204':
          description: Custom schema type was succefully removed
        '400':
          description: Bad request. This may happen when there are schemas or custom instances associated with this custom type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                SchemasAssigned:
                  value:
                    code: 400
                    status: Bad Request
                    message: Cannot delete custom schema type='CUSTOM_DOCUMENT' because there are custom entities associated with this type.
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
      operationId: DELETE-schema-remove-custom-schema-type
      security:
      - OAuth2:
        - schema.schema_manage
    put:
      summary: Upserting a custom schema type
      description: 'Performs the `UPSERT` operation. If a custom schema type with specified ID exists in the system, then it is updated. If it doesn''t exist, a new type is created.


        **Note**: When a custom entity type is created, a set of custom scopes is created, which allow managing custom instances of that type.'
      tags:
      - Custom Schema Type
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomSchemaTypeUpdate'
            example:
              name:
                en: Updated Custom Type
              metadata:
                version: 1
        description: ''
      responses:
        '201':
          description: Custom schema type was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdResponse'
              example:
                id: CUSTOM_PRODUCT
        '204':
          description: Custom schema type was successfully updated.
        '400':
          $ref: '#/components/responses/Bad_request_400_cl'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '409':
          description: Version validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 409
                status: Conflict
                message: 'Cannot find the entity with an id: CUSTOM_ORDER and version: 2. It is possible to update an entity with the latest version only. Fetch the entity to get the latest version.'
      operationId: PUT-schema-upsert-custom-schema-type
      security:
      - OAuth2:
        - schema.schema_manage
      parameters:
      - $ref: '#/components/parameters/trait_contentLanguage_header'
    servers:
    - url: https://api.emporix.io
components:
  schemas:
    ErrorResponse:
      required:
      - code
      - message
      - status
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        code:
          type: integer
          format: int32
        status:
          type: string
        message:
          type: string
        errorCode:
          type:
          - string
          - 'null'
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              type:
                type: string
              message:
                type: string
              moreInfo:
                type: string
    CustomSchemaTypeResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique id of the custom schema type.
        name:
          type: object
          description: Localized custom type name in a form of a map of translations.
        schemas:
          type: object
          description: Information about associated schemas. This field is only included if `expandSchemas` is set to `true`
        metadata:
          type: object
          properties:
            createdAt:
              type: string
              description: 'Date and time when the object was created, compliant with the ISO 8601 standard. For example: `2022-03-31T09:52:15.423Z`'
            modifiedAt:
              type: string
              description: 'Date and time when the object was last modified, compliant with the ISO 8601 standard. For example: `2022-03-31T09:52:15.423Z`'
            version:
              type: integer
    IdResponse:
      type: object
      properties:
        id:
          type: string
          description: ID of the generated document.
      example:
        id: e343dc9e-a3f6-4573-bb01-a8ae21d2d4ae
      description: Id of the created schema.
    CustomSchemaTypeUpdate:
      type: object
      properties:
        name:
          type: object
          description: Localized custom type name in a form of a map of translations.
        metadata:
          type: object
          properties:
            version:
              type: integer
              description: Version of the custom schema type. If provided, it will be validated against the current entity version.
      required:
      - name
    CustomSchemaTypeCreation:
      type: object
      properties:
        id:
          type: string
          description: Unique code for the custom type. Can contain uppercase letters, digits, and underscores. The first character must be a letter.
        name:
          type: object
          description: Localized custom type name in a form of a map of translations.
      required:
      - id
      - name
    CustomSchemaTypesResponse:
      type: array
      items:
        $ref: '#/components/schemas/CustomSchemaTypeResponse'
  parameters:
    trail_xTotalCount_header:
      name: X-Total-Count
      in: header
      required: false
      schema:
        type: boolean
        example: true
        default: false
      description: 'Flag indicating whether the total number of retrieved items should be returned.

        '
    trait_expand_schemas:
      name: expandSchemas
      in: query
      description: 'Determines whether the response will include information about associated schemas.

        '
      schema:
        default: false
        type: boolean
    trait_fields:
      name: fields
      in: query
      description: 'Fields to be included in the response.

        '
      schema:
        type: string
    trait_paged_pageNumber:
      name: pageNumber
      in: query
      description: 'Page number to be retrieved. The number of the first page is 1.

        '
      schema:
        default: 1
        minimum: 1
        type: integer
    trait_contentLanguage_header:
      in: header
      name: Content-Language
      description: The Content-Language request HTTP header defines language(s) of the payload.
      schema:
        type: string
        example: de
    tenant:
      name: tenant
      in: path
      required: true
      description: 'Your Emporix tenant name.


        **Note**: Always write the tenant name in lowercase.

        '
      schema:
        pattern: ^[a-z][a-z0-9]+$
        minLength: 3
        maxLength: 16
        type: string
    trait_q_param:
      name: q
      in: query
      description: "A standard query parameter is used to search for specific values.\n\n* Searching for items by string-based properties:\n  * By a field value: `q=siteCode:main`, where `siteCode` is the field name, and `main` is its desired value.\n  * By a value that is not equal to the specified value: `q=id:!=64d35aa7fa54121ca47db657`, where `id` is the field name, and `64d35aa7fa54121ca47db657` is the excluded schema ID.\n  * By a localized field value: `q=items.product.name.en:apple_lobo`, where `name` is the field name of product, `en` is the language code, and `apple_lobo` is the field value expressed in the specified language. **Note**: This query works only for localized fields, which are stored in a map format, where `key` is the language code and `value` is the translation to particular language.\n* Searching for items by a number-based property:\n  * With a specific value: `q=items.quantity.quantity:20`\n  * With a value greater than: `q=items.quantity.quantity:>20`\n  * With a value lower than: `q=items.quantity.quantity:<20`\n  * With a value greater than or equal to: `q=items.quantity.quantity:>=20`\n  * With a value lower than or equal to: `q=items.quantity.quantity:<=20`\n  * With a value within a range of values: `q=items.quantity.quantity:(>=10 AND <=20)`\\\n   where `items.quantity.quantity` is the name of the number-based field, and `20` is its querying value.\n* Searching for items by a date-based property: All number-based property queries are also valid for dates. In that case, the date should be placed within double quotes: `q=metadataCreatedAt:(>=\"2021-05-18T07:27:27.455Z\" AND <\"2021-05-20T07:27:27.455Z\")`\n* Searching for items by a boolean-based property: `q=description.multiLanguage:true`, where `description.multiLanguage` is the boolean field name, and `true` is its desired value.\n* Searching for items with a nonexistent or empty property: `q=description.en:null`, where `description.en` is the field that has its value set to `null`.\n* Searching for items with an existing property: `q=mixins.mixinName:exists`, where the specific mixin named `mixinName` exists in the database.\n* Searching for items by multiple specific values: `q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494)`, where `id` is the field name, and strings within the bracket are the desired values.\n* Searching for items by multiple fields: `q=id:5c3325baa9812100098ff48f siteCode:main` where `id` and `siteCode` are field names. All objects that contain the specified values are returned. Multiple fields (separated by space) can be specified. Multiple values for each field can also be specified in the format presented earlier.\n* Searching for items with string-based properties conforming to a regex: `q=siteCode:~ain` or `q=code:(~U PL)` - in case of searching for strings with space, where `siteCode` is the name of the field, and `ain` or `U PL` is its querying regex.\n* Searching for items with a localized string-based property conforming to a regex: `items.product.name.en:~(Yoghurt im)` - where `name` is the product field name, `en` is the desired language, and `Joghurt im` is the search term.\n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)\n"
      schema:
        type: string
        example: siteCode:{main}
    trait_acceptLanguage_header:
      name: Accept-Language
      in: header
      required: false
      schema:
        type: string
      description: 'List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields. If a value is specified, then it must be present in the tenant configuration.

        * If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.

        * If the header is set to `*`, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.

        * If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

        '
    trait_paged_pageSize:
      name: pageSize
      in: query
      description: 'Number of items to be retrieved per page.

        '
      schema:
        default: 60
        minimum: 1
        type: integer
    trait_sort:
      name: sort
      in: query
      description: "List of properties used to sort the results, separated by colons. The order of properties indicates their priority in sorting.\n\nPossible values:\n* `{fieldName}`\n* `{fieldName}:asc`\n* `{fieldName}:desc`\n\n**Note:** If you want to sort the results by localized properties, the possible values are:\n  * `{fieldName}.{language}`\n  * `{fieldName}.{language}:asc`\n  * `{fieldName}.{language}:desc`\n\nIf the sorting direction is not specified, the fields are sorted in ascending order."
      schema:
        type: string
  responses:
    Not_Found_404:
      description: Given resource cannot be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Schema does not exists:
              value:
                resourceId: 084bcag6-66b8-4ddd-9489-65c5f6449e94
                code: 404
                status: Not Found
                message: Error while getting resource.
                details:
                - message: Resource with id '084bcaf6-66b8-4ddd-9489-65c5f6449e94' not found
    Forbidden_403:
      description: Permission denied due to insufficient rights. This may happen when the request does not contain sufficient scopes for the given query values.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Forbidden:
              value:
                code: 403
                status: Forbidden
                message: You need to choose the required scope to complete this action.
                details:
                - message: 'Required scope(s): schema.schema_manage'
    Bad_request_400_cl:
      description: Unsupported content language provided.
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              status:
                type: string
              message:
                type: string
              errorCode:
                type: string
              details:
                type: array
                items:
                  type: object
                  properties:
                    field:
                      type: string
                    type:
                      type: string
                    message:
                      type: string
                    moreInfo:
                      type: string
          examples:
            Bad request:
              value:
                code: 400
                status: Bad Request
                message: Language header validation failed.
                details:
                - message: 'Following languages are not supported: ''ru'''
    Unauthorized_401:
      description: Given request is unauthorized - the authorization token is invalid or has expired. It usually means that the tenant from the token does not match tenant from path.
      content:
        application/json:
          schema:
            type: object
            properties:
              fault:
                type: object
                properties:
                  faultstring:
                    type: string
                  detail:
                    type: object
                    properties:
                      errorcode:
                        type: string
          examples:
            Invalid Access Token:
              value:
                fault:
                  faultstring: Invalid Access Token
                  detail:
                    errorcode: keymanagement.service.invalid_access_token
            Unauthorized:
              value: {}
    Conflict_409:
      description: Conflict.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 409
            status: Conflict
            message: Duplicated key.
  examples:
    CustomSchemaTypeResponse:
      value:
        id: CUSTOM_PRODUCT
        name:
          en: Custom Product Type
        metadata:
          createdAt: '2023-08-09T09:21:42.693Z'
          modifiedAt: '2023-08-09T09:21:42.693Z'
          version: 1
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.emporix.io/oauth/token
          scopes:
            schema.schema_manage: Required for managing schemas.
            schema.schema_read: Required for reading schemas.
            schema.custominstance_read: Read custom instances of any custom schema type.
            schema.custominstance_manage: Manage custom instances of any custom schema type.
            custom.{lowerCaseType}_manage: Manage custom instances of a given type. For example, for type `DOCUMENT` → `custom.document_manage`.
            custom.{lowerCaseType}_manage_own: Allows to manage only your own custom instances of a given type. For example, for type `DOCUMENT` → `custom.document_manage_own`.
            custom.{lowerCaseType}_read: Read custom instances of a given type. For example, for type `DOCUMENT` → `custom.document_read`.
            custom.{lowerCaseType}_read_own: Allows to read only your own custom instances of a given type. For example, for type `DOCUMENT` → `custom.document_read_own`.
x-refined-from:
- emporix-schema-openapi.yml
- emporix-schema-openapi.yml