Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update JSON Dictionary spec #2663

Merged
merged 14 commits into from
Apr 15, 2024
28 changes: 22 additions & 6 deletions docs/Design/fpp-json-dict.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,10 @@ This document describes the format of FPP JSON dictionaries.
- [Negative Infinity Values](#negative-infinity-values)
- [Commands, Telemetry Channels, Events, and Parameters](#commands-telemetry-channels-events-and-parameters)
- [Formal Parameters](#formal-parameters)
- [Parameters](#parameters)
- [Commands](#commands)
- [Telemetry Channels](#telemetry-channels)
- [Events](#events)
- [Parameters](#parameters)
- [Data Products](#data-products)
- [Records](#records)
- [Containers](#containers)
Expand Down Expand Up @@ -131,11 +131,12 @@ Example: Type Descriptor for booleans
```

## String Type Descriptors

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `name` | **String** representing the FPP type name | `string` | true |
| `kind` | **String** representing the kind of type | `string` | true |
| `size` | **Number** of bytes supported by the data type | **Number** in the range [0, 2<sup>31</sup>) | false |
| `size` | Maximum string size in bytes | **Number** in the range [0, 2<sup>31</sup>) | true |
thomas-bc marked this conversation as resolved.
Show resolved Hide resolved

### String Types
Any sequence of characters
Expand All @@ -145,7 +146,7 @@ Example Type Descriptor for string
{
"name": "string",
"kind": "string",
"size": 64,
"size": 80,
}
```

Expand Down Expand Up @@ -177,7 +178,7 @@ Example JSON of qualified name
| `qualifiedName` | Fully qualified name of element in FPP model | Period-separated **String** | true |
| `size` | Size of the data structure | **Number** | true |
| `elementType` | The type of the array's elements | **[Type Descriptor](#type-descriptors)** | true
| `default` | Default array value | Value of type specified in `elementType` | false |
| `default` | Default array value | Value of type specified in `elementType` | true |
| `annotation` | User-defined annotation | **String** | false |

Example FPP model with JSON representation:
Expand Down Expand Up @@ -206,16 +207,18 @@ module M1 {


## Enumeration Type Definition

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `kind` | The kind of type | `enum` | true |
| `qualifiedName` | Fully qualified name of element in FPP model | Period-separated **String** | true |
| `representationType` | Type of the enumerated values | **[Type Descriptor](#type-descriptors)** | true |
| `enumeratedConstants` | The enumerated constants | JSON Dictionary of enumerated constants (keys) to [Enumerated Constant Descriptor](#enumerated-constant-descriptors) (values) | true |
| `default` | Qualified name of the enumeration's default value | **String** | false |
| `default` | Qualified name of the enumeration's default value | **String** | true |
| `annotation` | User-defined annotation | **String** | false |

#### Enumerated Constant Descriptors

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `name` | Name of the enumerated constant | **String** | true |
Expand Down Expand Up @@ -266,15 +269,17 @@ module M1 {
## Struct Type Definition

### Struct Type Definition

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `kind` | The kind of type | `struct` | true |
| `qualifiedName` | Fully qualified name of element in FPP model | Period-separated **String** | true |
| `members` | The members of the struct | JSON dictionary of Member Name (key) to [Struct Member Descriptor](#struct-member-descriptor) (value) | true |
| `default` | The default value of the struct | JSON dictionary of Member Name (key) to default value (value) | false |
| `default` | The default value of the struct | JSON dictionary of Member Name (key) to default value (value) | true |
| `annotation` | User-defined annotation | **String** extracted from FPP model | false |

### Struct Member Descriptor

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `type` | [Type Descriptor](#type-descriptors) of member | [Type Descriptor](#type-descriptors) | true |
Expand Down Expand Up @@ -407,18 +412,21 @@ Example JSON of a struct:

## Invalid Values
### Null Values

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `name` | **String** indicating that the value is null | null | true |
| `kind` | **String** indicating that the kind of value is invalid | invalid | true |

### Infinity Values

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `name` | **String** indicating that the value is infinity| infinity | true |
| `kind` | **String** indicating that the kind of value is invalid | invalid | true |

### Negative Infinity Values

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `name` | **String** indicating that the value is negative infinity | negativeInfinity | true |
Expand Down Expand Up @@ -453,6 +461,7 @@ Formal Parameters are used in Commands and Events definitions.
```

## Commands

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `name` | Fully qualified name of the command | Period-separated **String** | true |
Expand Down Expand Up @@ -505,6 +514,7 @@ JSON representation:
```

## Telemetry Channels

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `name` | Fully qualified name of the telemetry channel | Period-separated **String** | true |
Expand Down Expand Up @@ -554,6 +564,7 @@ telemetry Channel1: F64 \
```

## Events

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `name` | Fully qualified name of the event | Period-separated **String** | true |
Expand Down Expand Up @@ -621,6 +632,7 @@ event Event1(
```

## Parameters

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `name` | Fully qualified name of the parameter | Period-separated **String** | true |
Expand Down Expand Up @@ -655,6 +667,7 @@ param Parameter1: U32 \

# Data Products
## Records

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `name` | Fully qualified name of the record | Period-separated **String** | true |
Expand Down Expand Up @@ -702,6 +715,7 @@ product record Record1: U32 id 0x102
```

## Containers

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `name` | Fully qualified name of the container | Period-separated **String** | true |
Expand Down Expand Up @@ -746,6 +760,7 @@ product container Container2 default priority 10

# Dictionaries
## Dictionary Metadata

| Field | Description | Options | Required |
| ----- | ----------- | ------- | -------- |
| `deploymentName` | **String** representing the deployment name | **String** | true |
Expand All @@ -764,6 +779,7 @@ product container Container2 default priority 10
```

## Dictionary Content

| Field | Content | Required |
| ----- | ------- | -------- |
| `metadata` | [Dictionary Metadata](#dictionary-metadata) | true |
Expand Down
Loading