JQL Fundamentals
Field selection and return shapes
How request bodies choose fields and how mutations use __meta__.return.
JQL field selection is graph-shaped. For reads, every non-__meta__ key in the request body describes a field to serialize. Use null for scalar fields and nested objects for related records.
Retrieve shape
1{
2 "__meta__": {
3 "schema": "model",
4 "namespace": "billing.Invoice",
5 "intent": "retrieveOne",
6 "authenticationClass": "jwt",
7 "uniqueObject": {
8 "id": 501
9 }
10 },
11 "id": null,
12 "invoiceNumber": null,
13 "status": null,
14 "account": {
15 "id": null,
16 "name": null
17 },
18 "items": [
19 {
20 "id": null,
21 "description": null,
22 "quantity": null,
23 "amount": null
24 }
25 ]
26}Nested fields are recursively serialized by resolving relation metadata or explicit nested __meta__.namespace values.
Aliases and transforms
A nested field can carry its own __meta__.alias. Transform directives can use __transform__ when a model field supports serializer transformations.
1{
2 "__meta__": {
3 "schema": "model",
4 "namespace": "system.User",
5 "intent": "retrieve",
6 "authenticationClass": "jwt",
7 "limit": 10
8 },
9 "id": null,
10 "fullName": {
11 "__transform__": {
12 "alias": "name",
13 "casing": "uppercase"
14 }
15 },
16 "email": null
17}Mutation return shapes
create, update, patch, and updateOrCreate use __meta__.return to decide what to serialize after the mutation. If you omit return, the payload may be sparse.
1{
2 "__meta__": {
3 "schema": "model",
4 "namespace": "objects.Record",
5 "intent": "update",
6 "authenticationClass": "jwt",
7 "uniqueObject": {
8 "id": 88
9 },
10 "return": {
11 "id": null,
12 "reference": null,
13 "additionalInformation": null
14 }
15 },
16 "additionalInformation": {
17 "companySize": "51-200",
18 "status": "qualified"
19 }
20}Annotated and aggregate fields
Fields may contain nested __meta__ directives for aggregate annotations or subqueries. Root aggregate requests use the same field-object pattern.
1{
2 "__meta__": {
3 "schema": "model",
4 "namespace": "assets.Asset",
5 "intent": "aggregate",
6 "authenticationClass": "jwt"
7 },
8 "assetCount": {
9 "__meta__": {
10 "field": "*",
11 "function": "count"
12 }
13 },
14 "totalValue": {
15 "__meta__": {
16 "field": "value",
17 "function": "sum"
18 }
19 }
20}Related: intents, objects records, and /developer/data-hooks.