> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-graphql-api/core-api-reference/common.md). # Common resources Foundational types, scalars, and interfaces shared across the API, including Node, Titled, Versioned, pagination types, and common scalars like DateTime and Decimal. {% hint style="warning" %} **Navixy GraphQL 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 (query) 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:**
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. |
*** ### 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:**
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. |
*** ## Objects ### DeletePayload The result of a delete mutation. | Field | Type | Description | | ----------- | ----- | ----------------------------- | | `deletedId` | `ID!` | The ID of the deleted entity. | *** ### 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](#countprecision)! | The precision level of the count value. | *** ### Money A monetary amount in minor units (cents) with currency. | Field | Type | Description | | ---------- | ---------------------- | ------------------------------------------------------------ | | `amount` | [Long](#long)! | Amount in minor currency units (for example, 1050 = $10.50). | | `currency` | [Currency](#currency)! | [ISO 4217](https://www.iso.org/standard/4217.html) currency. | *** ## 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. | *** ### Versioned An object that supports [optimistic locking](/docs/navixy-graphql-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. | *** ### 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](#pageinfo)! | Information about the current page. | | `total` | [CountInfo](#countinfo) | The total count of items matching the filter. | *** ### 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. Implies `Node`: values are stored on the holder and indexed by its id, so every holder is an addressable entity. Selecting `id` on a `Customizable` fragment therefore needs no concrete type. **Implements:** [Node](#node) | Field | Type | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `ID!` | A globally unique identifier. This ID is opaque and should not be parsed by clients. | | `customFields` | \[[CustomFieldValue](/docs/navixy-graphql-api/business-data-repository/api-reference/custom-fields.md#customfieldvalue)!]! | Typed custom field values, one entry per set field code. Each element is a concrete `CustomFieldValue` implementation matching the field's `FieldType` — select fields via inline fragments. The system-reserved code `geojson_data` is excluded — it is exposed through `GeoObject.geojsonData` instead. | *** ### 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. | *** ## Scalars ### 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` | | Specification | | *** ### 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` | | Specification | | *** ### 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 | | *** ### 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` | | Specification | | *** ### HexColorCode A hexadecimal color code. Supports 3-digit (`#RGB`) or 6-digit (`#RRGGBB`) format. | Property | Value | | ------------- | ------------------------------------------------------------------- | | Format | `#RRGGBB` | | Example | `#FF5733` | | Specification | | *** ### 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` | | Specification | | *** ### 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 | | *** ### 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 | | *** ### UUID A UUID ([RFC 9562](https://www.rfc-editor.org/rfc/rfc9562.html)) owned by a system outside this API — unlike `ID`, which is always a platform UUIDv8 carrying an entity-type discriminator. Never accepted by `node(id:)`. Moved here from `nvx4-api.graphql` when tracking needed it for `TrackingEvent.commandId`: an identifier this platform did not mint belongs to no single module, and the list of them grows with every neighbouring system (`organizationId` from Console, NTF's message id, a future command id). See `docs/todo/tracking-api-design-followups.md` for the open question of whether `ID` should simply become this. | Property | Value | | ------------- | ---------------------------------------- | | Specification | | *** ### 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 * Length: 1 to 100 characters (auto-generated codes are truncated to 30) Uniqueness: * For catalog items: unique within the same catalog and workspace scope * For custom field definitions: unique per owner catalog item and workspace * 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` | *** ### Long Signed 64-bit integer in the range \[-9223372036854775808, 9223372036854775807]. Encoded as a JSON number. | Property | Value | | -------- | ----------------------- | | Format | `64-bit signed integer` | | Example | `1234567890123456789` | *** ### Duration An [ISO 8601](https://www.iso.org/standard/8601.html) duration restricted to the fixed-length designators — `PnDTnHnMn.nS`, optionally signed. Examples: `PT5M` (five minutes), `PT1H30M`, `P1D`, `PT0.5S`, `-PT5M`. Always the ISO form, never a bare number of seconds and never a shorthand like `5m`: a duration that travels as a string with no agreed grammar is a duration every caller parses differently. The calendar designators are refused, not silently reinterpreted: `P1Y`, `P1M` and `P1W` all fail coercion. Their length is a question about a calendar and a time zone, and a duration on the wire carries neither — a month is 28 to 31 days, and a week is 168 hours only where no DST transition falls inside it. A caller that means a calendar step asks for a date range instead. `@specifiedBy` points at the Navixy page rather than at [ISO 8601](https://www.iso.org/standard/8601.html) or [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html), because the full grammar in either is precisely what this scalar does not accept — a pointer to it would describe the wrong type. The page restates the paragraphs above; those paragraphs and `ScalarCoercingTest.DurationCoercingTest` are the contract. *** ### 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 | | *** ### GeoJSON A bare GeoJSON geometry object ([RFC 7946](https://www.rfc-editor.org/rfc/rfc7946.html) §3.1) — one of the types `GeoJsonGeometryType` lists. The `Feature` and `FeatureCollection` wrappers are rejected everywhere this scalar is used, `GeoObject.geojsonData` and GEOJSON custom-field values alike: send `feature.geometry`, not the feature. | Property | Value | | ------------- | ------------------------------------------------- | | Format | `GeoJSON geometry object` | | Example | `{"type": "Point", "coordinates": [125.6, 10.1]}` | | Specification | | *** ### 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"` | *** ### Currency [ISO 4217](https://www.iso.org/standard/4217.html) three-letter currency code (for example: USD, EUR, JPY). *** ## See also * [Pagination](/docs/navixy-graphql-api/pagination.md) * [Filtering and sorting](/docs/navixy-graphql-api/filtering-and-sorting.md) * [Error handling](/docs/navixy-graphql-api/error-handling.md) * [Optimistic locking](/docs/navixy-graphql-api/optimistic-locking.md) * [Limits](/docs/navixy-graphql-api/limits.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://navixy.com/docs/navixy-graphql-api/core-api-reference/common.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.