title: Category
x-tags:
  - Catalog
type: object
description: Defines a category.
required:
  - uuid
  - model_type
  - name
  - tags
  - media
  - media_uuid
  - external_media_url
  - media_background_colour
  - availability
  - description
  - pos_tag_colour
  - entries
  - sub_categories
  - translations
  - created_at
properties:
  uuid:
    type: string
    format: uuid
    description: The category's unique identifier.
    readOnly: true
  model_type:
    enum:
      - category
    readOnly: true
  name:
    type: string
    description: The category's name.
    minLength: 1
    maxLength: 255
    example: Wraps
  tags:
    type: array
    uniqueItems: true
    description: The category's tags.
    items:
      type: string
      format: uuid
  media:
    oneOf:
      - type: 'null'
      - $ref: ./Media.yaml
    description: The media file that is associated with the category.
  media_uuid:
    type:
      - string
      - 'null'
    format: uuid
    description: |-
      The UUID of the media file to associate with the category.

      Catalog-management requests use this field to set or remove the association. Responses also include the resolved media file in `media`.
  external_media_url:
    type:
      - string
      - 'null'
    format: uri
    description: |-
      The URI of an external media file that is associated with the category.

      This field may be used when `media` is null as a fall-back to display a third-party asset in the application, such as an image hosted on the Deliverect CDN.
    readOnly: true
  media_background_colour:
    type:
      - string
      - 'null'
    description: The background colour that should be displayed behind (or in place of) media assets.
    example: '#F0F0F0'
    pattern: '^#(?:[A-Fa-f0-9]{3}|[A-Fa-f0-9]{6})$'
  availability:
    $ref: ./Availability.yaml
  description:
    type:
      - string
      - 'null'
    minLength: 1
    maxLength: 255
    example: Our delicious wraps are made fresh daily!
    description: The category's description.
  pos_tag_colour:
    type:
      - string
      - 'null'
    pattern: '^#(?:[A-Fa-f0-9]{3}|[A-Fa-f0-9]{6})$'
    example: '#F0F0F0'
    description: The colour used for the "category tag" in POS.
  entries:
    type: array
    uniqueItems: true
    description: Ordered UUIDs of directly associated items. Items from sub-categories are not included.
    items:
      type: string
      format: uuid
  sub_categories:
    type: array
    uniqueItems: true
    default: []
    description: |-
      Ordered UUIDs of child categories. These are regular categories that may be shared by multiple parents and independently included in menus. A category may contain both direct items and sub-categories. Each child retains its own availability, schedules, translations, media and tags.

      Catalog responses remain flat; resolve these UUIDs using the regular category models. Applications follow at most one level. The API rejects direct self-links but allows deeper links and indirect cycles.

      This field is returned at every supported API version, including an empty array when there are no links. Clients without sub-category navigation continue to use direct `entries`; child items are not flattened into that list.

      Duplicating a category retains links to the original children. Deleting a child removes its UUID from all parents; deleting a parent preserves its children and their items.
    items:
      type: string
      format: uuid
  translations:
    type: object
    description: The category's translated attributes.
    required:
      - name
      - description
    properties:
      name:
        allOf:
          - $ref: ./Translation.yaml
          - type: object
            required:
              - en
              - ms
              - zh
              - ta
              - hi
              - ja
              - ko
              - th
      description:
        allOf:
          - $ref: ./Translation.yaml
          - type: object
            required:
              - en
              - ms
              - zh
              - ta
              - hi
              - ja
              - ko
              - th
  created_at:
    type: string
    format: date-time
    description: The date-time that the category was created.
    readOnly: true
