# Common resources

{% hint style="warning" %}
**Navixy Repository API is a work in progress.** This documentation is published for preview purposes only and doesn't reflect a stable release. Structure, field names, and behaviors are subject to change.
{% endhint %}

Foundational types, scalars, and interfaces used throughout the API.

## Queries

### node

Retrieves any entity by its globally unique identifier.

```graphql
node(id: ID!): Node
```

**Arguments**

| Name | Type  | Description                       |
| ---- | ----- | --------------------------------- |
| `id` | `ID!` | The ID of the entity to retrieve. |

**Output types:**

<details>

<summary>Node</summary>

An object with a globally unique identifier.

| Field | Type  | Description                                                                          |
| ----- | ----- | ------------------------------------------------------------------------------------ |
| `id`  | `ID!` | A globally unique identifier. This ID is opaque and should not be parsed by clients. |

</details>

***

### nodes

Retrieves multiple entities by their globally unique identifiers. Returns items in the same order as the input IDs.

```graphql
nodes(ids: [ID!]!): [Node]!
```

**Arguments**

| Name  | Type     | Description                          |
| ----- | -------- | ------------------------------------ |
| `ids` | `[ID!]!` | The IDs of the entities to retrieve. |

**Output types:**

<details>

<summary>Node</summary>

An object with a globally unique identifier.

| Field | Type  | Description                                                                          |
| ----- | ----- | ------------------------------------------------------------------------------------ |
| `id`  | `ID!` | A globally unique identifier. This ID is opaque and should not be parsed by clients. |

</details>

***

## Objects

### PageInfo

Information about the current page in a paginated connection.

| Field             | Type       | Description                                                |
| ----------------- | ---------- | ---------------------------------------------------------- |
| `hasNextPage`     | `Boolean!` | Whether more items exist after the current page.           |
| `hasPreviousPage` | `Boolean!` | Whether more items exist before the current page.          |
| `startCursor`     | `String`   | The cursor pointing to the first item in the current page. |
| `endCursor`       | `String`   | The cursor pointing to the last item in the current page.  |

***

### CountInfo

Information about the total count of items in a connection.

| Field       | Type                                    | Description                             |
| ----------- | --------------------------------------- | --------------------------------------- |
| `count`     | `Int!`                                  | The count of items matching the filter. |
| `precision` | [CountPrecision](#type-countprecision)! | The precision level of the count value. |

***

### DeletePayload

The result of a delete mutation.

| Field       | Type  | Description                   |
| ----------- | ----- | ----------------------------- |
| `deletedId` | `ID!` | The ID of the deleted entity. |

***

## Enums

### OrderDirection

The direction for sorting query results.

| Value  | Description                                                                   |
| ------ | ----------------------------------------------------------------------------- |
| `ASC`  | Sort in ascending order (A→Z, 0→9, oldest→newest). NULL values appear last.   |
| `DESC` | Sort in descending order (Z→A, 9→0, newest→oldest). NULL values appear first. |

***

### CountPrecision

The precision level of a total count value.

| Value         | Description                                                                     |
| ------------- | ------------------------------------------------------------------------------- |
| `EXACT`       | The count is exact, calculated using `COUNT(*)`.                                |
| `APPROXIMATE` | The count is approximate, derived from table statistics.                        |
| `AT_LEAST`    | At least this many items exist. Counting stopped early for performance reasons. |

***

## Interfaces

### Node

An object with a globally unique identifier.

| Field | Type  | Description                                                                          |
| ----- | ----- | ------------------------------------------------------------------------------------ |
| `id`  | `ID!` | A globally unique identifier. This ID is opaque and should not be parsed by clients. |

***

### Titled

An object with a human-readable display name.

| Field   | Type      | Description                      |
| ------- | --------- | -------------------------------- |
| `title` | `String!` | The human-readable display name. |

***

### Customizable

An object that supports custom field values.

| Field          | Type    | Description                                                                                                                                                                                                                          |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `customFields` | `JSON!` | Custom field values as a key-value map. Keys are `CustomFieldDefinition` codes. System-reserved codes (`geojson_data`, `schedule_data`) are excluded from this map and exposed through dedicated typed fields on the entity instead. |

***

### Versioned

An object that supports [optimistic locking](/docs/navixy-repository-api/optimistic-locking.md) for concurrency control.

| Field     | Type   | Description                                                                                                                                                                                               |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version` | `Int!` | The version number for optimistic locking. Incremented on each update. Can be provided in update/delete mutations to prevent lost updates. If omitted, the update proceeds without stale-read protection. |

***

### MultiValue

An interface for field parameters that support selecting multiple values.

| Field     | Type       | Description                                             |
| --------- | ---------- | ------------------------------------------------------- |
| `isMulti` | `Boolean!` | Whether multiple values can be selected for this field. |

***

### Edge

An edge in a paginated connection.

| Field    | Type      | Description                                          |
| -------- | --------- | ---------------------------------------------------- |
| `cursor` | `String!` | An opaque cursor for this edge, used for pagination. |

***

### Connection

A paginated connection following the Relay Cursor Connections specification.

| Field      | Type                         | Description                                   |
| ---------- | ---------------------------- | --------------------------------------------- |
| `pageInfo` | [PageInfo](#type-pageinfo)!  | Information about the current page.           |
| `total`    | [CountInfo](#type-countinfo) | The total count of items matching the filter. |

***

## Scalars

### DateTime

An [ISO 8601](https://www.iso.org/standard/8601.html) datetime string with timezone ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Example: `2024-01-15T10:30:00Z`.

| Property      | Value                                                    |
| ------------- | -------------------------------------------------------- |
| Format        | `YYYY-MM-DDTHH:mm:ss.sssZ`                               |
| Example       | `2025-01-15T14:30:00.000Z`                               |
| Specification | <https://scalars.graphql.org/chillicream/date-time.html> |

***

### Date

An [ISO 8601](https://www.iso.org/standard/8601.html) date string without time component ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Example: `2024-01-15`.

| Property      | Value                                               |
| ------------- | --------------------------------------------------- |
| Format        | `YYYY-MM-DD`                                        |
| Example       | `2025-01-15`                                        |
| Specification | <https://scalars.graphql.org/chillicream/date.html> |

***

### JSON

An arbitrary JSON value. Can be an object, array, string, number, boolean, or null.

| Property      | Value                                    |
| ------------- | ---------------------------------------- |
| Format        | `Any valid JSON`                         |
| Example       | `{"key": "value", "count": 42}`          |
| Specification | <https://www.rfc-editor.org/rfc/rfc8259> |

***

### GeoJSON

A GeoJSON geometry object ([RFC 7946](https://www.rfc-editor.org/rfc/rfc7946.html)). Supports Point, LineString, Polygon, and other geometry types.

| Property      | Value                                             |
| ------------- | ------------------------------------------------- |
| Format        | `GeoJSON geometry object`                         |
| Example       | `{"type": "Point", "coordinates": [125.6, 10.1]}` |
| Specification | <https://www.rfc-editor.org/rfc/rfc7946>          |

***

### Latitude

A geographic latitude coordinate in decimal degrees. Valid range: -90.0 to 90.0.

| Property | Value           |
| -------- | --------------- |
| Format   | `-90.0 to 90.0` |
| Example  | `37.7749`       |

***

### Longitude

A geographic longitude coordinate in decimal degrees. Valid range: -180.0 to 180.0.

| Property | Value             |
| -------- | ----------------- |
| Format   | `-180.0 to 180.0` |
| Example  | `-122.4194`       |

***

### Locale

A BCP 47 language tag identifying a user locale. Example: `en-US`, `es-MX`, `fr-CA`.

| Property      | Value                                                       |
| ------------- | ----------------------------------------------------------- |
| Format        | `language-REGION`                                           |
| Example       | `en-US`                                                     |
| Specification | <https://the-guild.dev/graphql/scalars/docs/scalars/locale> |

***

### EmailAddress

An email address conforming to [RFC 5322](https://www.rfc-editor.org/rfc/rfc5322.html). Example: `user@example.com`.

| Property | Value              |
| -------- | ------------------ |
| Format   | `user@domain`      |
| Example  | `user@example.com` |

***

### HexColorCode

A hexadecimal color code. Supports 3-digit (`#RGB`) or 6-digit (`#RRGGBB`) format.

| Property | Value     |
| -------- | --------- |
| Format   | `#RRGGBB` |
| Example  | `#FF5733` |

***

### CountryCode

An [ISO 3166](https://www.iso.org/standard/3166.html)-1 alpha-2 country code. Example: `US`, `GB`, `ES`.

| Property | Value                   |
| -------- | ----------------------- |
| Format   | `Two uppercase letters` |
| Example  | `US`                    |

***

### Code

A machine-readable identifier code.

Constraints:

* Allowed characters: ASCII letters (a-z, A-Z), digits (0-9), underscore (\_), dot (.), hyphen (-)
* Must start with a letter or digit
* Case-preserving: the original casing is stored as provided
* Case-insensitive for uniqueness checks and comparisons
* Maximum length: 64 characters

Uniqueness:

* For catalog items: unique within the same catalog and organization scope
* For custom field definitions: unique per owner catalog item and organization
* For field options (OPTIONS type): unique within a single field definition
* Additional uniqueness requirements may apply depending on context (see individual fields)

Examples: DEVICE\_TYPE, vehicle\_car, status.active, sensor-v2, ABC123

| Property      | Value                                      |
| ------------- | ------------------------------------------ |
| Format        | `UPPER_SNAKE_CASE`, `lower_snake_case`     |
| Example       | `DEVICE_TYPE`, `vehicle_type`              |
| Specification | <https://api.navixy.com/spec/scalars/code> |

***

### Decimal

Arbitrary-precision decimal value encoded as a JSON string (e.g. `"5.25"`). String encoding avoids the precision loss inherent in JSON `Float`.

Values exceeding the declared `scale` of a decimal custom field are rounded server-side using HALF\_UP (round half away from zero for positive values, round half toward zero for negative — matches Java `RoundingMode.HALF_UP`). The rounded value is persisted in both the CFV table and the `custom_fields_data` JSONB blob; raw un-rounded input is never stored.

Storage is `numeric(28, 10)` — up to 28 significant digits, of which at most 10 follow the decimal point (so up to 18 digits before). Values exceeding this envelope (e.g. more than 18 integer digits) are rejected as `VALIDATION_ERROR` at the API layer.

| Property      | Value                                                                                 |
| ------------- | ------------------------------------------------------------------------------------- |
| Format        | `String-encoded decimal number`                                                       |
| Example       | `"123.456"`                                                                           |
| Specification | <https://www.navixy.com/docs/navixy-repository-api/core-api-reference/common#decimal> |

***

### Long

Signed 64-bit integer in the range \[-9223372036854775808, 9223372036854775807]. Encoded as a JSON number.

| Property      | Value                                                                              |
| ------------- | ---------------------------------------------------------------------------------- |
| Format        | `64-bit signed integer`                                                            |
| Example       | `1234567890123456789`                                                              |
| Specification | <https://www.navixy.com/docs/navixy-repository-api/core-api-reference/common#long> |

***


---

# 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://navixy.com/docs/navixy-repository-api/core-api-reference/common.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.