# Get Enumeration Literals

## API Name

API Name: Enumeration Literals – Get

***

## Overview

This API returns enumeration literals (lookup values) for a given property or tag.

MBSE Core uses this API to:

* Populate dropdown values for properties and tags
* Validate lookup values during element creation and update
* Ensure consistent ID-to-name mapping

Connector responsibility:

* Call the end system API to fetch enumeration literals for the specified property or tag.
* Determine whether the identifier refers to a property or a tag using `isTag`.
* Convert the result into `MbseEnumerationLiteral` format.
* Return a list of enumeration literals containing only `id` and `name`.

***

### API URI

```bash
GET: /mbse/api/1.0/properties/{propertyOrTagId}/enumeration-literals
    ?projectId={projectId}
    &elementTypeId={elementTypeId}
    &isTag={isTag}
```

***

### Path Parameters

| Name            | Mandatory | Type   | Description                                                            |
| --------------- | --------- | ------ | ---------------------------------------------------------------------- |
| propertyOrTagId | True      | String | ID of the property or tag for which enumeration literals are required. |

***

### URI Parameters

| Name          | Mandatory | Type    | Description                                                                           |
| ------------- | --------- | ------- | ------------------------------------------------------------------------------------- |
| projectId     | True      | String  | ID of the project.                                                                    |
| elementTypeId | True      | String  | ID of the element type provided in element types JSON.                                |
| isTag         | True      | Boolean | Indicates whether `propertyOrTagId` refers to a tag (`true`) or a property (`false`). |

***

### Behavior Rules

1. The API must be scoped to:
   * `projectId`
   * `elementTypeId`
2. If `isTag = true`:
   * Fetch enumeration literals for the specified tag.
3. If `isTag = false`:
   * Fetch enumeration literals for the specified property.
4. The response must contain:
   * Only `id` and `name`.
5. Duplicate literals must not be returned.
6. If no enumeration literals are defined:
   * Return an empty list.

***

### Response Payload

#### Sample Response

```json
[
  {
    "id": "1",
    "name": "High"
  },
  {
    "id": "2",
    "name": "Medium"
  },
  {
    "id": "3",
    "name": "Low"
  }
]
```

***

### Response Parameters

#### Enumeration Literal Object

| Name | Required | Type   | Description                                   |
| ---- | -------- | ------ | --------------------------------------------- |
| id   | True     | String | Unique identifier of the enumeration literal. |
| name | True     | String | Display name of the enumeration literal.      |

***

### Ordering Requirement

Enumeration literals should be returned in a deterministic order.

Recommended behavior:

* Sort by `name` in ascending order.
* Alternatively, preserve system-defined ordering if meaningful.

The `MbseEnumerationLiteral` class supports alphabetical sorting by `name`.

***

### Error Handling

| HTTP Status | Description                                                |
| ----------- | ---------------------------------------------------------- |
| 400         | Invalid request parameters.                                |
| 404         | Property or tag not found.                                 |
| 500         | Internal server error while fetching enumeration literals. |

***

### Example Use Case

#### Get Enumeration Literals for a Property

```bash
GET /mbse/api/1.0/properties/status/enumeration-literals?
projectId=123
&elementTypeId=Block
&isTag=false
```

#### Get Enumeration Literals for a Tag

```bash
GET /mbse/api/1.0/properties/criticality/enumeration-literals?
projectId=123
&elementTypeId=Block
&isTag=true
```

***

### Implementation Guidelines

* Validate that the property or tag supports lookup values.
* Ensure mapping between end system ID and MBSE ID is stable.
* Do not return UI-only values.
* Ensure no null values are returned.
* Keep response lightweight and efficient.

***

### Design Rationale

Enumeration literals provide controlled vocabulary for:

* Lookup properties
* Tagged values
* Status fields
* Priority fields
* Custom classifications

This API ensures consistent value mapping and safe validation across heterogeneous MBSE systems.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://opstech.gitbook.io/opstech-docs/7.223/mbse-connector-sdk-index/mbse-sdk-connector-apis/metadata-apis/enumeration-literals.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.