openapi: 3.0.1 info: title: Schema Service description: | Manage the mixins schemas for miscellaneous types. contact: email: documentation@emporix.com version: '' servers: - url: 'https://api.emporix.io' paths: '/schema/{tenant}/schemas': parameters: - $ref: '#/components/parameters/tenant' post: tags: - Schema summary: Creating a schema description: | Creates a schema entity and generates json-schema representation which is then uploaded to cloudinary repository. *** ### Required scopes * `schema.schema_manage` - required for creating a schema operationId: POST-schema-create-schema requestBody: content: application/json: schema: $ref: '#/components/schemas/SchemaCreation' examples: Schema: value: name: en: Product Custom Attributes types: - PRODUCT attributes: - key: weight name: en: Weight of a product description: en: The exact weight of a product in grams. type: TEXT metadata: readOnly: true required: true - key: size name: en: Size of a product description: en: The exact size of a product. Possible values are S, M, L. type: ENUM metadata: readOnly: true required: true values: - value: S - value: M - value: L - key: advertisement name: en: Advertisement of a product description: en: A localized advertisement of a product. type: TEXT metadata: localized: true required: true Schema Array: value: name: en: Product Custom Attributes types: - PRODUCT attributes: - key: arrDecimal name: en: Array Decimal type: ARRAY arrayType: type: DECIMAL metadata: {} - key: arrText name: en: Array Text type: ARRAY arrayType: type: TEXT localized: true metadata: {} - key: arrDateTime name: en: Array Date Time type: ARRAY arrayType: type: DATE_TIME metadata: {} - key: arrEnum name: en: Array Enum type: ARRAY arrayType: type: ENUM values: - value: S - value: M - value: L metadata: {} Schema Object: value: name: en: Product Custom Attributes types: - PRODUCT attributes: - key: person name: en: Person type: OBJECT metadata: {} attributes: - key: name name: en: Name type: TEXT metadata: {} - key: age name: en: Age type: NUMBER metadata: {} - key: address name: en: Address type: OBJECT metadata: {} attributes: - key: street name: en: Street metadata: {} type: TEXT - key: city name: en: City type: TEXT metadata: {} - key: zipcode name: en: Zip Code type: TEXT metadata: {} description: '' responses: '201': description: The request was successful. The Schema has been created. content: application/json: schema: $ref: '#/components/schemas/IdResponse' examples: Schema created: value: id: e241dc9e-a3f6-4573-bb01-a8ae21d2d4ae '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 schemas description: |- Retrieves all schemas. You can filter the results with query parameters. tags: - Schema responses: '200': description: '' headers: X-Total-Count: description: Total amount of schemas for given criteria. schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/SchemasResponse' examples: Schemas: $ref: '#/components/examples/SchemasResponse' '400': $ref: '#/components/responses/Bad_request_400' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' operationId: GET-schema-retrieve-schemas 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' - name: type in: query description: | Filters schemas by type. Possible types to specify, CART, CATEGORY, COMPANY, COUPON, CUSTOMER, CUSTOMER.ADDRESS, ORDER, PRODUCT, QUOTE, RETURN, PRICE_LIST, SITE, CUSTOM_ENTITY, VENDOR. When the newest version of the schema is of different type than the previous one and the previous one matches the type specified in this query param, then the previous version is returned. schema: type: string '/schema/{tenant}/schemas/{id}': parameters: - $ref: '#/components/parameters/tenant' - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/trait_schemaVersion' get: summary: Retrieving a schema description: |- Retrieves a single schema. tags: - Schema responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SchemaResponse' examples: Schema: $ref: '#/components/examples/SchemaResponse' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' '404': $ref: '#/components/responses/Not_Found_404' operationId: GET-schema-retrieve-schema parameters: - $ref: '#/components/parameters/trait_acceptLanguage_header' delete: summary: Deleting a schema description: |- Deletes a single schema. It deletes just a database entry. The cloudinary reference file remains untouched. *** **Required scopes** * `schema.schema_manage` tags: - Schema responses: '204': description: 'No content' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' operationId: DELETE-schema-remove-schema security: - OAuth2: - schema.schema_manage put: summary: Updating a schema description: |- Updates a single schema. Each update releases a new version of json schema file. **Required scopes** * `schema.schema_manage` tags: - Schema requestBody: content: application/json: schema: $ref: '#/components/schemas/SchemaUpdate' examples: Schema: value: name: en: Product Custom Attributes types: - PRODUCT attributes: - key: weight name: en: Weight of a product description: en: The exact weight of a product in grams. type: TEXT metadata: readOnly: true required: true - key: size name: en: Size of a product description: en: The exact size of a product. Possible values are S, M, L. type: ENUM metadata: readOnly: true required: true values: - value: S - value: M - value: L - key: advertisement name: en: Advertisement of a product description: en: A localized advertisement of a product. type: TEXT metadata: localized: true required: true metadata: version: 1 description: '' responses: '204': description: 'No content' '400': $ref: '#/components/responses/Bad_request_400_cl' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' '404': $ref: '#/components/responses/Not_Found_404' '409': $ref: '#/components/responses/Conflict_409' operationId: PUT-schema-update-schema security: - OAuth2: - schema.schema_manage parameters: - $ref: '#/components/parameters/trait_contentLanguage_header' '/schema/{tenant}/schemas/{id}/types': parameters: - $ref: '#/components/parameters/tenant' - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/version' - $ref: '#/components/parameters/trait_mode' put: summary: Updating types of a schema description: |- Updates assigned types to the schema. It's allowed to change the assigned types to the newest schema as well as to the previous versions of the schema. This operation does not generate a new version of the schema. **Required scopes** * `schema.schema_manage` tags: - Type requestBody: content: application/json: schema: $ref: '#/components/schemas/SchemaTypes' examples: SchemaTypes: value: - PRODUCT - ORDER description: '' responses: '204': description: 'No content' '400': $ref: '#/components/responses/Bad_request_400_cl' '401': $ref: '#/components/responses/Unathorized_401' '403': $ref: '#/components/responses/Forbidden_403' '404': $ref: '#/components/responses/Not_Found_404' operationId: PUT-schema-update-schema-types security: - OAuth2: - schema.schema_manage '/schema/{tenant}/schemas/file': parameters: - $ref: '#/components/parameters/tenant' post: tags: - Schema summary: Providing a file description: | Validates and parses provided json schema file. When the file is valid, it returns a json which can be used either to create a new schema via POST operation or to update an existing one via PUT operation when all the missing fields are provided. It doesn't create any file and it doesn't crease a database entity. operationId: POST-schema-parse-schema-file requestBody: content: multipart/form-data: schema: type: object properties: file: type: object format: json description: Content of the file. id: type: string description: Id of the existing schema. Should be null when there is no existing schema. required: - file description: '' responses: '200': description: The request was successful. The file was validated and parsed correctly. content: application/json: schema: $ref: '#/components/schemas/SchemaFileResponse' examples: Schemas: $ref: '#/components/examples/SchemaFileResponse' '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' '/schema/{tenant}/types': parameters: - $ref: '#/components/parameters/tenant' get: summary: Retrieving types description: |- Retrieves types which have at least one schema assigned. tags: - Type responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/TypesResponse' examples: Types: value: - ORDER - PRODUCT - QUOTE '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' operationId: GET-schema-retrieve-schema-types '/schema/{tenant}/references': parameters: - $ref: '#/components/parameters/tenant' post: tags: - Reference summary: Creating a reference description: | Creates a reference entity and uploads provided file to the cloudinary repository. *** ### Required scopes * `schema.schema_manage` - required for creating a reference operationId: POST-schema-create-reference requestBody: content: multipart/form-data: schema: type: object properties: file: type: object format: json description: Content of the file. body: $ref: '#/components/schemas/ReferenceCreation' required: - file - body examples: Reference: value: file: externalValue: 'https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/653a30c0951b2b0665884f89_v1.json' body: name: en: Product Custom Attributes types: - PRODUCT description: '' responses: '201': description: The request was successful. The Reference has been created. content: application/json: schema: $ref: '#/components/schemas/IdResponse' examples: Reference created: value: id: e241dc9e-a3f6-4573-bb01-a8ae21d2d4ae '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 references description: |- Retrieves all references. You can filter the results with query parameters. tags: - Reference responses: '200': description: '' headers: X-Total-Count: description: Total amount of references for given criteria. schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/ReferencesResponse' examples: References: $ref: '#/components/examples/ReferencesResponse' '400': $ref: '#/components/responses/Bad_request_400' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' operationId: GET-schema-retrieve-references 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' - name: type in: query description: | Filters references by type. Possible types to specify, CART, CATEGORY, COMPANY, COUPON, CUSTOMER, CUSTOMER_ADDRESS, ORDER, PRODUCT, QUOTE, RETURN, PRICE_LIST, SITE, CUSTOM_ENTITY, VENDOR. When the newer version of a reference is of different type than the previous one and the previous one matches the type specified in this query param, then the previous version is returned. schema: type: string '/schema/{tenant}/references/{id}': parameters: - $ref: '#/components/parameters/tenant' - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/trait_schemaVersion' get: summary: Retrieving a reference description: |- Retrieves a single reference. tags: - Reference responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ReferenceResponse' examples: Reference: $ref: '#/components/examples/ReferenceResponse' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' '404': $ref: '#/components/responses/Not_Found_404' operationId: GET-schema-retrieve-reference parameters: - $ref: '#/components/parameters/trait_acceptLanguage_header' delete: summary: Deleting a reference description: |- Deletes a single reference. It deletes just a database entry. The cloudinary reference file remains untouched. *** **Required scopes** * `schema.schema_manage` tags: - Reference responses: '204': description: 'No content' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' operationId: DELETE-schema-remove-reference security: - OAuth2: - schema.schema_manage put: summary: Updating a reference description: |- Updates a single reference. **Required scopes** * `schema.schema_manage` tags: - Reference requestBody: content: multipart/form-data: schema: type: object properties: file: type: object format: json description: Content of the file. body: $ref: '#/components/schemas/ReferenceUpdate' required: - file - body examples: Reference: value: file: externalValue: 'https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/653a30c0951b2b0665884f89_v1.json' body: name: en: Product Custom Attributes types: - PRODUCT metadata: version: 1 description: '' responses: '204': description: 'No content' '400': $ref: '#/components/responses/Bad_request_400_cl' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' '404': $ref: '#/components/responses/Not_Found_404' '409': $ref: '#/components/responses/Conflict_409' operationId: PUT-schema-update-reference security: - OAuth2: - schema.schema_manage parameters: - $ref: '#/components/parameters/trait_contentLanguage_header' '/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. *** ### Required scopes * `schema.schema_manage` - required for creating a custom schema type 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 - code: 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' '/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. *** **Required scopes** * `schema.schema_manage` - required for removing custom schema type 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. **Required scopes** * `schema.schema_manage` - required for upserting custom schema 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' '/schema/{tenant}/custom-entities/{type}/instances': parameters: - $ref: '#/components/parameters/tenant' - $ref: '#/components/parameters/type' post: tags: - Custom Instance summary: Creating a custom instance parameters: - $ref: '#/components/parameters/trait_contentLanguage_header' - $ref: '#/components/parameters/trait_validateReferences' description: | Creates a custom instance entity associated with given custom schema type. *** ### Required scopes * `schema.custominstance_manage` - required for creating a custom instance operationId: POST-schema-create-custom-instance requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomInstanceCreation' examples: Basic custom instance: value: id: '123' name: en: Report mixins: productCustomAttributes: inStock: true popularity: 1 metadata: mixins: productCustomAttributes: 'https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn-v38.json' Custom instance with reference: value: name: en: Report mixins: order_reference: order: emporixReferenceType: ORDER id: EON1007 metadata: mixins: order_reference: 'https://res.cloudinary.com/saas-ag/raw/upload/schemata2/tenant/order_reference_v1.json' responses: '201': description: Custom instance was successfully created. content: application/json: schema: $ref: '#/components/schemas/IdResponse' example: id: '123' '400': $ref: '#/components/responses/Bad_request_400_mixins' '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 get: summary: Retrieving all custom instances description: |- Retrieves all custom instances associated with a specific custom schema type. *** ### Required scopes * `schema.custominstance_read` - required for retrieving custom instances tags: - Custom Instance responses: '200': description: '' headers: X-Total-Count: description: Total amount of custom instances for given criteria. schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/CustomInstancesResponse' examples: Basic response: value: - id: '123' name: en: Report type: CUSTOM_DOCUMENT mixins: productCustomAttributes: inStock: true populatirty: 1 media: - media_id_1 - media_id_2 metadata: mixins: productCustomAttributes: 'https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn-v38.json' createdAt: '2025-04-17T13:00:00.000Z' modifiedAt: '2025-05-14T13:00:00.000Z' version: 3 - id: '456' name: en: Manual type: CUSTOM_DOCUMENT media: - media_id_3 metadata: createdAt: '2025-04-17T13:00:00.000Z' modifiedAt: '2025-04-17T13:00:00.000Z' version: 1 Response with expanded references: value: - id: '68fe97bb616cd70336cde7ee' name: en: Report type: CUSTOM_DOCUMENT mixins: customAttributes: references: product_reference: emporixReferenceType: PRODUCT id: '68fe97af4e412504678a4fd7' yrn: 'urn:yaas:saasag:caasproduct:product:tenant;68fe97af4e412504678a4fd7' code: hammer1 name: en: Hammer productType: BASIC published: true metadata: version: 1 createdAt: '2025-10-26T21:50:39.097Z' modifiedAt: '2025-10-26T21:50:39.097Z' expandStatus: SUCCESS customers_array: - emporixReferenceType: CUSTOMER id: '79474954' title: MR firstName: John lastName: Doe preferredCurrency: EUR type: CUSTOMER metadata: version: 0 customerNumber: '79474954' contactEmail: john.doe@email.com active: true onHold: false metadataCreatedAt: '2025-10-26T21:49:41.440Z' businessModel: B2C expandStatus: SUCCESS - emporixReferenceType: CUSTOMER id: '16229890' expandStatus: FAILURE error: message: Entity not found details: - "Entity with id: '16229890' was not found for type: 'CUSTOMER'" media: - media_id_1 - media_id_2 metadata: version: 2 createdAt: '2025-10-26T21:50:51.702Z' modifiedAt: '2025-10-26T21:51:16.434Z' mixins: customAttributes: 'https://res.cloudinary.com/saas-ag/raw/upload/schemata2/tenant/customAttributes_v2.json' '400': $ref: '#/components/responses/Bad_request_400' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' operationId: GET-schema-retrieve-custom-instances parameters: - $ref: '#/components/parameters/trail_xTotalCount_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_acceptLanguage_header' - $ref: '#/components/parameters/trait_expand_references' '/schema/{tenant}/custom-entities/{type}/instances/{id}': parameters: - $ref: '#/components/parameters/tenant' - $ref: '#/components/parameters/type' - $ref: '#/components/parameters/id' get: summary: Retrieving a custom instance parameters: - $ref: '#/components/parameters/trait_acceptLanguage_header' - $ref: '#/components/parameters/trait_expand_references' description: |- Retrieves a single custom instance by id. *** ### Required scopes * `schema.custominstance_read` - required for retrieving a custom instance tags: - Custom Instance responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CustomInstanceResponse' examples: Basic response: value: id: "123" name: en: Report type: CUSTOM_DOCUMENT mixins: productCustomAttributes: inStock: true populatirty: 1 media: - media_id_1 - media_id_2 metadata: mixins: productCustomAttributes: 'https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn-v38.json' createdAt: '2025-04-17T13:00:00.000Z' modifiedAt: '2025-05-14T13:00:00.000Z' version: 3 Response with expanded references: value: id: '68fe97bb616cd70336cde7ee' name: en: Report type: CUSTOM_DOCUMENT mixins: customAttributes: references: product_reference: emporixReferenceType: PRODUCT id: '68fe97af4e412504678a4fd7' yrn: 'urn:yaas:saasag:caasproduct:product:tenant;68fe97af4e412504678a4fd7' code: hammer1 name: en: Hammer productType: BASIC published: true metadata: version: 1 createdAt: '2025-10-26T21:50:39.097Z' modifiedAt: '2025-10-26T21:50:39.097Z' expandStatus: SUCCESS customers_array: - emporixReferenceType: CUSTOMER id: '79474954' title: MR firstName: John lastName: Doe preferredCurrency: EUR type: CUSTOMER metadata: version: 0 customerNumber: '79474954' contactEmail: john.doe@email.com active: true onHold: false metadataCreatedAt: '2025-10-26T21:49:41.440Z' businessModel: B2C expandStatus: SUCCESS - emporixReferenceType: CUSTOMER id: '16229890' expandStatus: FAILURE error: message: Entity not found details: - "Entity with id: '16229890' was not found for type: 'CUSTOMER'" media: - media_id_1 - media_id_2 metadata: version: 2 createdAt: '2025-10-26T21:50:51.702Z' modifiedAt: '2025-10-26T21:51:16.434Z' mixins: customAttributes: 'https://res.cloudinary.com/saas-ag/raw/upload/schemata2/tenant/customAttributes_v2.json' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' '404': $ref: '#/components/responses/Not_Found_404' operationId: GET-schema-retrieve-custom-instance delete: summary: Deleting a custom instance description: |- Deletes a custom instance. *** **Required scopes** * `schema.custominstance_manage` tags: - Custom Instance responses: '204': description: 'No content' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' operationId: DELETE-schema-remove-custom-instance security: - OAuth2: - schema.schema_manage put: summary: Upserting a custom instance parameters: - $ref: '#/components/parameters/trait_contentLanguage_header' - $ref: '#/components/parameters/trait_validateReferences' description: |- Performs the `UPSERT` operation. If a custom instance with specified ID exists in the system, then it is updated. If it doesn't exist, a new custom instance is created. **Required scopes** * `schema.custominstance_manage` - required for upserting a custom instance tags: - Custom Instance requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomInstanceUpdate' example: name: { "en": "Report" } mixins: { productCustomAttributes: { inStock: false, popularity: 2 } } metadata: { mixins: { "productCustomAttributes": 'https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn-v38.json' }, version: 1 } description: '' responses: '201': description: Custom instance was successfully created. content: application/json: schema: $ref: '#/components/schemas/IdResponse' example: id: '123' '204': description: 'Custom instance was successfully updated' '400': $ref: '#/components/responses/Bad_request_400_mixins' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 409 status: Conflict message: 'Cannot find the entity with an id: 123 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-instance security: - OAuth2: - schema.schema_manage patch: summary: Patching a custom instance parameters: - $ref: '#/components/parameters/trait_contentLanguage_header' - $ref: '#/components/parameters/trait_validateReferences' description: |- The patch request consists of set of operation, that should be defined according to [RFC-6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. **Required scopes** * `schema.custominstance_manage` - required for patching a custom instance tags: - Custom Instance requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/PatchOperation' examples: Update a name: value: - op: replace path: /name value: en: New name Remove mixins: value: - op: remove path: /mixins/productCustomAttributes Add a mixin: value: - op: ADD path: /mixins/productCustomAttributes/pricingMeasurePrice value: 15 description: '' responses: '204': description: 'Custom instance was successfully patched' '400': $ref: '#/components/responses/Bad_request_400_mixins' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' '404': $ref: '#/components/responses/Not_Found_404' operationId: PATCH-schema-patch-custom-instance security: - OAuth2: - schema.schema_manage '/schema/{tenant}/custom-entities/{type}/instances/search': parameters: - $ref: '#/components/parameters/tenant' - $ref: '#/components/parameters/type' post: summary: Searching for custom instances description: |- Returns all custom instances for provided type that match specified criteria. *** ### Required scopes * `schema.custominstance_read` - required for retrieving custom instances tags: - Custom Instance requestBody: content: application/json: schema: type: object properties: q: type: string description: A standard query parameter used to search for specific values. example: q: mixins.productCustomAttributes.inStock:true responses: '200': description: 'Custom instances succesfully retrieved' content: application/json: schema: $ref: '#/components/schemas/CustomInstancesResponse' examples: Basic response: value: - id: '123' name: en: Report type: CUSTOM_DOCUMENT mixins: productCustomAttributes: inStock: true populatirty: 1 media: - media_id_1 - media_id_2 metadata: mixins: productCustomAttributes: 'https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn-v38.json' createdAt: '2025-04-17T13:00:00.000Z' modifiedAt: '2025-05-14T13:00:00.000Z' version: 3 Response with expanded references: value: - id: '68fe97bb616cd70336cde7ee' name: en: Report type: CUSTOM_DOCUMENT mixins: customAttributes: references: product_reference: emporixReferenceType: PRODUCT id: '68fe97af4e412504678a4fd7' yrn: 'urn:yaas:saasag:caasproduct:product:tenant;68fe97af4e412504678a4fd7' code: hammer1 name: en: Hammer productType: BASIC published: true metadata: version: 1 createdAt: '2025-10-26T21:50:39.097Z' modifiedAt: '2025-10-26T21:50:39.097Z' expandStatus: SUCCESS customers_array: - emporixReferenceType: CUSTOMER id: '79474954' title: MR firstName: John lastName: Doe preferredCurrency: EUR type: CUSTOMER metadata: version: 0 customerNumber: '79474954' contactEmail: john.doe@email.com active: true onHold: false metadataCreatedAt: '2025-10-26T21:49:41.440Z' businessModel: B2C expandStatus: SUCCESS - emporixReferenceType: CUSTOMER id: '16229890' expandStatus: FAILURE error: message: Entity not found details: - "Entity with id: '16229890' was not found for type: 'CUSTOMER'" media: - media_id_1 - media_id_2 metadata: version: 2 createdAt: '2025-10-26T21:50:51.702Z' modifiedAt: '2025-10-26T21:51:16.434Z' mixins: customAttributes: 'https://res.cloudinary.com/saas-ag/raw/upload/schemata2/tenant/customAttributes_v2.json' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' operationId: POST-schema-search-custom-instances parameters: - $ref: '#/components/parameters/trail_xTotalCount_header' - $ref: '#/components/parameters/trait_paged_pageNumber' - $ref: '#/components/parameters/trait_paged_pageSize' - $ref: '#/components/parameters/trait_sort' - $ref: '#/components/parameters/trait_acceptLanguage_header' - $ref: '#/components/parameters/trait_fields' - $ref: '#/components/parameters/trait_expand_references' '/schema/{tenant}/custom-entities/{type}/instances/bulk': parameters: - $ref: '#/components/parameters/tenant' - $ref: '#/components/parameters/type' post: summary: Creating custom instances in bulk description: |- Creates multiple custom instances. *** ### Required scopes * `schema.custominstance_manage` - required for creating custom instances tags: - Custom Instance parameters: - $ref: '#/components/parameters/trait_validateReferences_bulk' requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/CustomInstanceCreation' example: - id: '123' name: { "en": "Report" } mixins: { productCustomAttributes: { inStock: true, popularity: 1 } } metadata: { mixins: { "productCustomAttributes": 'https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn-v38.json' } } - id: '456' name: { "en": "Manual" } responses: '207': description: 'Bulk operation was successful' content: application/json: schema: $ref: '#/components/schemas/BulkResponse' example: - index: 0 code: 201 status: Created - index: 1 code: 409 status: Conflict message: Custom instance with id='456' already exists for type='CUSTOM' '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' operationId: POST-schema-create-custom-instances-bulk put: summary: Upserting custom instances in bulk description: |- Upserts multiple custom instances. *** ### Required scopes * `schema.custominstance_manage` - required for upserting custom instances tags: - Custom Instance parameters: - $ref: '#/components/parameters/trait_validateReferences_bulk' requestBody: content: application/json: schema: type: array items: allOf: - type: object properties: id: type: string description: Custom instance id required: - id - $ref: '#/components/schemas/CustomInstanceUpdate' example: - id: '123' name: { "en": "Report" } mixins: { productCustomAttributes: { inStock: true, popularity: 1 } } metadata: { mixins: { "productCustomAttributes": 'https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn-v38.json' } } - id: '456' name: { "en": "Manual" } responses: '207': description: 'Bulk operation was successful' content: application/json: schema: $ref: '#/components/schemas/BulkResponse' example: - index: 0 code: 201 status: Created - index: 1 code: 204 status: No Content '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' operationId: PUT-schema-create-custom-instances-bulk delete: summary: Deleting custom instances in bulk description: |- Removes multiple custom instances. ### The IDs of items should be defined in the request body as an array of strings. #### Example: `["firstId", "secondId", "thirdId"]` *** ### Required scopes * `schema.custominstance_manage` - required for deleting custom instances tags: - Custom Instance responses: '207': description: 'Bulk operation was successful' content: application/json: schema: $ref: '#/components/schemas/BulkResponse' example: - index: 0 code: 204 status: No Content - index: 1 code: 204 status: No Content '401': $ref: '#/components/responses/Unauthorized_401' '403': $ref: '#/components/responses/Forbidden_403' operationId: DELETE-schema-create-custom-instances-bulk components: examples: SchemaFileResponse: value: id: 64d35aa7fa54121ca47db657 name: en: Product Custom Attributes attributes: - key: weight type: NUMBER metadata: readOnly: true localized: false required: true metadata: version: 1 SchemaResponse: value: id: 64d35aa7fa54121ca47db657 name: en: Product Custom Attributes attributes: - key: weight name: en: Weight of a product description: en: The exact weight of a product in grams. type: NUMBER metadata: readOnly: true localized: false required: true types: - PRODUCT metadata: version: 1 createdAt: "2023-08-09T09:21:42.693Z" modifiedAt: "2023-08-09T09:21:42.693Z" url: "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/64d35aa7fa54121ca47db657_v1.json" SchemasResponse: value: - id: 64d35aa7fa54121ca47db657 name: en: Product Custom Attributes attributes: - key: weight name: en: Weight of a product description: en: The exact weight of a product in grams. type: NUMBER metadata: readOnly: true localized: false required: true types: - PRODUCT metadata: version: 1 createdAt: "2023-08-09T09:21:42.693Z" modifiedAt: "2023-08-09T09:21:42.693Z" url: "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/64d35aa7fa54121ca47db657_v1.json" ReferenceResponse: value: id: 64d35aa7fa54121ca47db657 name: en: Product Custom Attributes types: - PRODUCT metadata: version: 1 createdAt: "2023-08-09T09:21:42.693Z" modifiedAt: "2023-08-09T09:21:42.693Z" url: "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/64d35aa7fa54121ca47db657_v1.json" ReferencesResponse: value: - id: 64d35aa7fa54121ca47db657 name: en: Product Custom Attributes types: - PRODUCT metadata: version: 1 createdAt: "2023-08-09T09:21:42.693Z" modifiedAt: "2023-08-09T09:21:42.693Z" url: "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/64d35aa7fa54121ca47db657_v1.json" TypesResponse: value: - ORDER - PRODUCT - QUOTE 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 CustomSchemaTypesResponse: value: - code: CUSTOM_PRODUCT name: en: Custom Product Type description: en: A custom type for specialized product schemas metadata: createdAt: "2023-08-09T09:21:42.693Z" modifiedAt: "2023-08-09T09:21:42.693Z" - code: CUSTOM_ORDER name: en: Custom Order Type description: en: A custom type for specialized order schemas metadata: createdAt: "2023-08-10T10:15:30.123Z" modifiedAt: "2023-08-10T10:15:30.123Z" schemas: ErrorResponse: required: - code - message - status type: object properties: id: type: string nullable: true code: type: integer format: int32 status: type: string message: type: string errorCode: type: string nullable: true details: type: array items: type: object properties: field: type: string type: type: string message: type: string moreInfo: type: string 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. SchemaType: type: string description: Type which the schema should be assigned to. Can be one of the predefined values or any custom schema type id. enum: [CART, CATEGORY, COMPANY, COUPON, CUSTOMER, CUSTOMER_ADDRESS, ORDER, PRODUCT, QUOTE, RETURN, PRICE_LIST, SITE, CUSTOM_ENTITY, VENDOR] SchemaTypes: type: array description: List of types to which assign the schema. items: $ref: '#/components/schemas/SchemaType' SchemaAttributeType: type: string description: | Type of the attribute. **Note**: The `REFERENCE` type is only available for custom schema types. enum: [TEXT, NUMBER, DECIMAL, BOOLEAN, DATE, TIME, DATE_TIME, ENUM, ARRAY, OBJECT, REFERENCE] Localized: type: boolean description: Whether the attribute is localized or not. Only attributes of 'TEXT' type can be localized. SchemaAttributeMetadata: type: object description: Metadata of the schema attribute. properties: readOnly: type: boolean description: Whether the attribute is read-only or not. localized: $ref: '#/components/schemas/Localized' required: type: boolean description: Whether the attribute is required or not. Attributes of 'BOOLEAN' type cannot be required. nullable: type: boolean description: Whether the attribute could accept null or not. SchemaAttributeValue: type: object description: | Value of the attribute. Valid for `ENUM` and `REFERENCE` types. For `ENUM` type, the value represents one of the allowed enum values. For `REFERENCE` type, the value represents the reference type (e.g., `PRODUCT`, `ORDER`, `CART`, `PRICE`, `CUSTOMER`, `COMPANY`, `MEDIA`, `PRICE_LIST`, `CUSTOMER_SEGMENT`, `CATEGORY`, or any custom schema type). properties: value: type: string required: - value SchemaFileAttributeResponse: type: object description: Schema attribute. properties: key: type: string description: Unique key of the attribute. metadata: $ref: '#/components/schemas/SchemaAttributeMetadata' values: type: array description: List of available values for the attribute. Only valid for `ENUM` and `REFERENCE` types. items: $ref: '#/components/schemas/SchemaAttributeValue' SchemaAttribute: type: object description: Schema attribute. properties: key: type: string description: Unique key of the attribute. name: type: object description: Localized schema name in a form of a map of translations. description: type: object description: Localized schema description in a form of a map of translations. type: $ref: '#/components/schemas/SchemaAttributeType' metadata: $ref: '#/components/schemas/SchemaAttributeMetadata' values: type: array description: List of available values for the attribute. Only valid for `ENUM` and `REFERENCE` type. items: $ref: '#/components/schemas/SchemaAttributeValue' attributes: type: array description: Object's properties. It can only be provided for attribute of `OBJECT` type. items: $ref: '#/components/schemas/SchemaAttribute' arrayType: type: object description: Contains information about the type used inside an array. It can only be provided for attribute of `ARRAY` type. properties: type: $ref: '#/components/schemas/SchemaAttributeType' values: type: array description: List of available values for the attribute. Only valid for `ENUM` and `REFERENCE` type. items: $ref: '#/components/schemas/SchemaAttributeValue' localized: $ref: '#/components/schemas/Localized' required: - type required: - key - name - type - metadata AbstractSchemaRequest: type: object properties: name: type: object description: Localized schema name in a form of a map of translations. types: type: array description: List of types which schema should be assigned to. items: $ref: '#/components/schemas/SchemaType' required: - name - types SchemaRequest: allOf: - $ref: '#/components/schemas/AbstractSchemaRequest' type: object properties: attributes: type: array description: List of attributes related to the schema. items: $ref: '#/components/schemas/SchemaAttribute' required: - attributes SchemaCreation: allOf: - $ref: '#/components/schemas/SchemaRequest' - type: object properties: id: type: string description: Identifier of the schema. SchemaUpdate: allOf: - $ref: '#/components/schemas/SchemaRequest' - type: object properties: metadata: $ref: '#/components/schemas/SchemaMetadataUpdate' ReferenceCreation: allOf: - $ref: '#/components/schemas/AbstractSchemaRequest' - type: object properties: id: type: string description: Identifier of the schema. ReferenceUpdate: allOf: - $ref: '#/components/schemas/AbstractSchemaRequest' - type: object properties: metadata: $ref: '#/components/schemas/SchemaMetadataUpdate' SchemaMetadataUpdate: type: object properties: version: type: number description: Version of the object. The value is required during update operation. SchemaMetadata: allOf: - $ref: '#/components/schemas/SchemaMetadataUpdate' - type: object description: Metadata of schema. properties: url: type: string description: Schema url of the attributes. 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`' SchemaFileResponse: type: object properties: id: type: string description: Identifier of the schema. attributes: type: array description: List of attributes related to the schema. items: $ref: '#/components/schemas/SchemaFileAttributeResponse' metadata: allOf: - $ref: '#/components/schemas/SchemaMetadataUpdate' AbstractSchemaResponse: type: object properties: id: type: string description: Identifier of the schema. name: type: object description: Localized schema name in a form of a map of translations. types: type: array description: List of types to which schema should be assigned. items: $ref: '#/components/schemas/SchemaType' metadata: allOf: - $ref: '#/components/schemas/SchemaMetadata' SchemaResponse: allOf: - $ref: '#/components/schemas/AbstractSchemaResponse' - type: object properties: attributes: type: array description: List of attributes related to the schema. items: $ref: '#/components/schemas/SchemaAttribute' SchemasResponse: type: array items: $ref: '#/components/schemas/SchemaResponse' ReferenceResponse: allOf: - $ref: '#/components/schemas/AbstractSchemaResponse' ReferencesResponse: type: array items: $ref: '#/components/schemas/ReferenceResponse' TypesResponse: type: array items: type: string CustomSchemaTypeCreation: type: object properties: id: type: string description: Unique code for the custom type. Can only contain uppercase letters and underscores. name: type: object description: Localized custom type name in a form of a map of translations. required: - id - name 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 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 CustomSchemaTypesResponse: type: array items: $ref: '#/components/schemas/CustomSchemaTypeResponse' CustomInstanceCreation: type: object properties: id: type: string description: Id of the custom instance. name: type: object description: Localized custom type name in a form of a map of translations. mixins: type: string description: A key-value map of additional attributes. metadata: type: object properties: mixins: type: object description: A key-value map, where key is a mixin name and value is a link to the mixin schema. CustomInstanceUpdate: type: object properties: name: type: object description: Localized custom type name in a form of a map of translations. mixins: type: string description: A key-value map of additional attributes. metadata: type: object properties: version: type: integer description: Version of the custom instance. If provided, it will be validated against the current entity version. mixins: type: object description: A key-value map, where key is a mixin name and value is a link to the mixin schema. CustomInstanceResponse: type: object properties: id: type: string description: Unique identifier of the custom instance. name: type: object description: Localized custom type name in a form of a map of translations. type: type: string description: Custom schema type to which custom instance is related. mixins: type: string description: A key-value map of additional attributes. media: type: array description: List of media IDs assigned to the custom instance. items: type: string metadata: allOf: - $ref: '#/components/schemas/CustomInstanceMetadata' CustomInstancesResponse: type: array items: $ref: '#/components/schemas/CustomInstanceResponse' BulkResponse: type: array items: type: object properties: index: type: integer description: Index of the processed item, matching the item position in request body. code: type: integer description: HTTP Status Code. status: type: string description: HTTP Status description message: type: string description: Error message. details: type: array items: type: object properties: message: type: string description: Error details. CustomInstanceMetadata: 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 description: Version of the custom instance. mixins: type: object description: A key-value map, where key is a mixin name and value is a link to the mixin schema. PatchOperation: type: object properties: op: type: string enum: - add - remove - replace description: 'Indicates an operation which should be done on a return. Available operations: `add` `remove` and `replace`' path: type: string description: 'Indicates a path for which the value should be applied. For example:`/mixins/additionalAttributes/externalId` or `/name`' value: oneOf: - type: object - type: string - type: number description: 'Indicates a value that should be changed or added. The value can be of a primitive type, like string, number, boolean or it can be an object or an array.' required: - op - path securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: 'https://api.emporix.io/oauth/token' scopes: schema.schema_manage: '' schema.schema_read: '' parameters: trait_validateReferences: name: validateReferences in: query required: false schema: type: boolean default: true description: | When set to true, references are validated if the provided resources exist. If set to false, validation is skipped. trait_validateReferences_bulk: name: validateReferences in: query required: false schema: type: boolean default: false description: | When set to true, references are validated if the provided resources exist. If set to false, validation is skipped. type: name: type in: path required: true description: Custom schema type to which custom instance is associated schema: example: CUSTOM_DOCUMENT type: string 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 id: name: id in: path required: true schema: type: string description: Unique identifier of the entity. version: name: version in: query required: true schema: type: integer description: Version of the entity. trait_schemaVersion: name: version in: query required: false schema: type: integer description: Version of the entity. example: 1 trait_mode: name: mode in: query required: false schema: type: string enum: [REPLACE, ADD, REMOVE] default: REPLACE description: Defines how types assigned to given schema should be resolved. REPLACE is a default value. REPLACE takes provided types and replaces the existing ones with it. ADD adds provided types to the existing ones. REMOVE removes provided types from the existing ones. 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_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. Possible values: * `{fieldName}` * `{fieldName}:asc` * `{fieldName}:desc` **Note:** If you want to sort the results by localized properties, the possible values are: * `{fieldName}.{language}` * `{fieldName}.{language}:asc` * `{fieldName}.{language}:desc` If the sorting direction is not specified, the fields are sorted in ascending order. schema: type: string trait_paged_pageSize: name: pageSize in: query description: | Number of items to be retrieved per page. schema: default: 60 minimum: 1 type: integer trait_fields: name: fields in: query description: | Fields to be included in the response. schema: type: string trait_expand_schemas: name: expandSchemas in: query description: | Determines whether the response will include information about associated schemas. schema: default: false type: boolean trait_expand_references: name: expand in: query required: false schema: type: string description: | Fetches data about expanded references. You can provide full path to the reference, use wildcard character `*`, or provide a specific index (starting with 0) in array of references. Multiple paths can be specified by separating them with commas. **Examples:** * `customAttributes.references.product_reference` - expands a specific reference * `*` - expands all references * `customAttributes.*` - expands all references within customAttributes * `customAttributes.references.customers_array.0` - expands the first element in an array of references trait_q_param: name: q in: query description: | A standard query parameter is used to search for specific values. * Searching for items by string-based properties: * By a field value: `q=siteCode:main`, where `siteCode` is the field name, and `main` is its desired value. * 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. * Searching for items by a number-based property: * With a specific value: `q=items.quantity.quantity:20` * With a value greater than: `q=items.quantity.quantity:>20` * With a value lower than: `q=items.quantity.quantity:<20` * With a value greater than or equal to: `q=items.quantity.quantity:>=20` * With a value lower than or equal to: `q=items.quantity.quantity:<=20` * With a value within a range of values: `q=items.quantity.quantity:(>=10 AND <=20)`\ where `items.quantity.quantity` is the name of the number-based field, and `20` is its querying value. * 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")` * 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. * 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`. * Searching for items with an existing property: `q=mixin:exists`, where `mixin` is the field that has a non-empty value. * 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. * 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. * 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. * 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. schema: type: string example: 'siteCode:{main}' 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 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. 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. responses: 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: {} Bad_request_400: description: Unsupported language provided. content: application/json: schema: type: object properties: code: type: integer status: type: string message: type: string details: type: array items: type: object properties: field: type: string type: type: string message: type: string moreInfo: type: string examples: Unsupported language: value: code: 400 status: Bad Request message: Language header validation failed. details: - message: 'Following languages are not supported: ''ru''' Bad_request_400_mixins: description: Mixins validation failed. 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: There is a validation error. Please check the details.. details: - message: 'null: instance type (boolean) does not match any allowed primitive type (allowed: ["integer","number"]): [mixins:productCustomAttributes:popularity]' 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''' Unathorized_401: description: Given request is unauthorized - the authorization token is invalid or has expired. It usually means that 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: {} 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' Conflict_409: description: Conflict. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 409 status: Conflict message: Duplicated key. 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 security: - OAuth2: [] tags: - name: Schema - name: Type - name: Reference - name: Custom Schema Type - name: Custom Instance