# Get Properties

## API Name

API Name: Properties – Get Metadata

***

## Overview

This API returns metadata information for properties applicable to a given element type.

MBSE Core uses this API to:

* Understand property definitions
* Validate element creation and update requests
* Identify mandatory fields
* Determine data types and formatting
* Support multi-select and lookup behavior
* Support time and date formatting

Connector responsibility:

* Call the end system API to retrieve property metadata for:
  * Given `projectId`
  * Given `elementTypeId`
  * Optional `metaType`
  * Optional `stereotypes`
* Convert the response into `MbsePropertyMeta` format.
* Return complete and accurate metadata definitions.

***

### API URI

```bash
GET: /mbse/api/1.0/properties
    ?projectId={projectId}
    &elementTypeId={elementTypeId}
    &metaType={metaType}
    &stereotypes={stereotypes}
```

***

### URI Parameters

| Name          | Mandatory | Type   | Description                                                              |
| ------------- | --------- | ------ | ------------------------------------------------------------------------ |
| projectId     | True      | String | ID of the project.                                                       |
| elementTypeId | True      | String | ID of the element type as defined in element types JSON.                 |
| metaType      | False     | String | UML metatype of the element (e.g., `uml:Class`, `uml:Signal`).           |
| stereotypes   | False     | List   | Qualified names or names provided in element types JSON for stereotypes. |

***

### Behavior Rules

1. Metadata must be scoped to:
   * `projectId`
   * `elementTypeId`
2. If `metaType` is provided:
   * Return properties applicable to that UML metatype.
3. If `stereotypes` are provided:
   * Return stereotype-specific properties.
4. If neither `metaType` nor `stereotypes` are provided:
   * Return base properties applicable to the element type.
5. The response must include:
   * Data type information
   * Mandatory flag
   * Multi-select flag
   * Read-only flag
6. Connector must not return duplicate property definitions.

***

### Response Payload

#### Sample Response

```json
[
  {
    "id": "status",
    "name": "Status",
    "dataType": "LOOKUP",
    "isMandatory": true,
    "isMultiSelect": false,
    "isReadOnly": false,
    "timeUnit": null,
    "dateFormat": null,
    "canBeSetAtElementCreateTime": true,
    "updateStepNumber": 1
  },
  {
    "id": "estimatedDuration",
    "name": "Estimated Duration",
    "dataType": "TIME_UNIT",
    "isMandatory": false,
    "isMultiSelect": false,
    "isReadOnly": false,
    "timeUnit": "DAYS",
    "dateFormat": null,
    "canBeSetAtElementCreateTime": true,
    "updateStepNumber": 2
  }
]
```

***

### Response Parameters

#### Property Metadata Object

| Name                        | Required | Type    | Description                                                        |
| --------------------------- | -------- | ------- | ------------------------------------------------------------------ |
| id                          | True     | String  | Unique identifier of the property.                                 |
| name                        | True     | String  | Display name of the property.                                      |
| dataType                    | True     | Enum    | Data type of the property.                                         |
| isMandatory                 | True     | Boolean | Indicates whether the property is mandatory.                       |
| isMultiSelect               | True     | Boolean | Indicates whether the property supports multiple values.           |
| isReadOnly                  | True     | Boolean | Indicates whether the property is read-only.                       |
| timeUnit                    | False    | Enum    | Applicable only for `TIME_UNIT` data type.                         |
| dateFormat                  | False    | String  | Date format if property represents a date string.                  |
| canBeSetAtElementCreateTime | False    | Boolean | Indicates whether the property can be set during element creation. |
| updateStepNumber            | False    | Integer | Update step number if multi-step updates are supported.            |

***

### Supported Data Types

The `dataType` field may contain the following values:

* `TEXT`
* `HTML`
* `WIKI`
* `MARKDOWN`
* `LOOKUP`
* `DATE_STRING`
* `BOOLEAN`
* `NUMBER`
* `USERNAME_AS_USER`
* `EMAIL_AS_USER`
* `TIME_UNIT`

#### User Data Types

* `USERNAME_AS_USER`
* `EMAIL_AS_USER`

#### Time Unit

If `dataType = TIME_UNIT`, the `timeUnit` field value must be one of the following:

Examples:

* `SECONDS`
* `MINUTES`
* `HOURS`
* `DAYS`

***

### Error Handling

| HTTP Status | Description                                    |
| ----------- | ---------------------------------------------- |
| 400         | Invalid request parameters.                    |
| 404         | Project or element type not found.             |
| 500         | Internal server error while fetching metadata. |

***

### Example Use Case

#### Get Property Metadata for Element Type

```bash
GET /mbse/api/1.0/properties?
projectId=123
&elementTypeId=Block
```

#### Get Property Metadata for Specific Metatype and Stereotype

```bash
GET /mbse/api/1.0/properties?
projectId=123
&elementTypeId=Block
&metaType=uml:Class
&stereotypes=SysML::Blocks::Block
```

***

### Implementation Guidelines

* Map end system property definitions accurately to `MbsePropertyMeta`.
* Ensure consistent data type mapping.
* Avoid returning UI-only or system-internal properties unless required.
* Maintain stable property IDs across API calls.
* Validate mandatory flags carefully.
* Return deterministic ordering of properties if possible.

***

### Design Rationale

This API provides the foundation for:

* Validation during create/update
* Lookup value retrieval
* Synchronization correctness

Accurate property metadata ensures the MBSE Connector behaves predictably and integrates cleanly with heterogeneous modeling 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/properties-list.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.