or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

colors.mddata-formats.mddate-time.mdfinancial.mdgeographic.mdidentifiers.mdindex.mdnetwork.mdnumeric.mdspecialized.mdstring-text.mdutilities.md
tile.json

data-formats.mddocs/

Data Format Scalars

JSON and structured data format validation. These scalars provide validation for common data interchange formats used in APIs, configuration files, and data storage.

Capabilities

JSON Scalar

Validates JSON data of any type.

/**
 * GraphQL scalar for JSON data validation
 * Accepts any valid JSON value (object, array, string, number, boolean, null)
 */
const GraphQLJSON: GraphQLScalarType;

Example Values:

  • {"name": "John", "age": 30} (Object)
  • [1, 2, 3, "hello"] (Array)
  • "simple string" (String)
  • 42 (Number)
  • true (Boolean)
  • null (Null)

JSONObject Scalar

Validates JSON objects specifically (not arrays, strings, etc.).

/**
 * GraphQL scalar for JSON object validation
 * Accepts only JSON objects (key-value pairs), not arrays or primitives
 */
const GraphQLJSONObject: GraphQLScalarType;

Example Values:

  • {"name": "John", "age": 30}
  • {"settings": {"theme": "dark", "notifications": true}}
  • {"items": [1, 2, 3], "total": 3}
  • {} (Empty object)

GeoJSON Scalar

Validates GeoJSON format for geographic data.

/**
 * GraphQL scalar for GeoJSON validation
 * Accepts GeoJSON geometry objects, features, and feature collections
 */
const GraphQLGeoJSON: GraphQLScalarType;

Example Values:

Point:

{
  "type": "Point",
  "coordinates": [-73.9857, 40.7484]
}

LineString:

{
  "type": "LineString",
  "coordinates": [
    [-73.9857, 40.7484],
    [-73.9857, 40.7584]
  ]
}

Polygon:

{
  "type": "Polygon",
  "coordinates": [[
    [-73.9857, 40.7484],
    [-73.9557, 40.7484],
    [-73.9557, 40.7784],
    [-73.9857, 40.7784],
    [-73.9857, 40.7484]
  ]]
}

Feature:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [-73.9857, 40.7484]
  },
  "properties": {
    "name": "Central Park"
  }
}

Usage Examples

import { 
  GraphQLJSON,
  GraphQLJSONObject,
  GraphQLGeoJSON
} from "graphql-scalars";

// In a GraphQL schema
const UserType = new GraphQLObjectType({
  name: "User",
  fields: {
    preferences: { type: GraphQLJSONObject },
    metadata: { type: GraphQLJSON },
    location: { type: GraphQLGeoJSON },
  },
});

const ConfigType = new GraphQLObjectType({
  name: "Config",
  fields: {
    settings: { type: GraphQLJSONObject },
    data: { type: GraphQLJSON },
  },
});

// Using with type definitions
const typeDefs = `
  scalar JSON
  scalar JSONObject
  scalar GeoJSON
  
  type User {
    id: ID!
    name: String!
    preferences: JSONObject
    metadata: JSON
    location: GeoJSON
  }
  
  type Location {
    name: String!
    coordinates: GeoJSON!
    properties: JSONObject
  }
  
  type Config {
    key: String!
    settings: JSONObject
    data: JSON
  }
`;

GraphQL Operations:

query GetUserWithPreferences($userId: ID!) {
  user(id: $userId) {
    id
    name
    preferences
    metadata
    location
  }
}

mutation UpdateUserPreferences($userId: ID!, $preferences: JSONObject!) {
  updateUserPreferences(userId: $userId, preferences: $preferences) {
    id
    preferences
  }
}

mutation SaveLocation($locationData: LocationInput!) {
  saveLocation(data: $locationData) {
    id
    name
    coordinates
    properties
  }
}

Variables:

{
  "userId": "user-123",
  "preferences": {
    "theme": "dark",
    "notifications": {
      "email": true,
      "push": false
    },
    "language": "en-US"
  },
  "locationData": {
    "name": "Central Park",
    "coordinates": {
      "type": "Point", 
      "coordinates": [-73.9857, 40.7484]
    },
    "properties": {
      "city": "New York",
      "country": "USA"
    }
  }
}

Validation Behavior

Each data format scalar performs specific validation:

  • JSON: Validates any JSON-parseable data, maintains original type
  • JSONObject: Validates only JSON objects, rejects arrays and primitives
  • GeoJSON: Validates against GeoJSON specification including geometry types and structure

Validation Examples:

// Valid JSON data
const validJSON = {
  jsonValue: {"key": "value"},     // Valid JSON object
  jsonArray: [1, 2, "three"],     // Valid JSON array
  jsonString: "hello",             // Valid JSON string
  jsonNumber: 42,                  // Valid JSON number
  jsonBoolean: true,               // Valid JSON boolean
  jsonNull: null                   // Valid JSON null
};

// Valid JSONObject data
const validJSONObject = {
  userSettings: {
    theme: "dark",
    notifications: true,
    preferences: {
      language: "en",
      timezone: "UTC"
    }
  }
};

// Invalid JSONObject data (valid JSON but not objects)
const invalidJSONObject = {
  arrayValue: [1, 2, 3],           // Valid JSON but not object
  stringValue: "not an object",    // Valid JSON but not object
  numberValue: 42                  // Valid JSON but not object
};

// Valid GeoJSON data
const validGeoJSON = {
  point: {
    type: "Point",
    coordinates: [-73.9857, 40.7484]
  },
  feature: {
    type: "Feature",
    geometry: {
      type: "Point",
      coordinates: [-73.9857, 40.7484]
    },
    properties: {
      name: "Location"
    }
  }
};

GeoJSON Types Support

The GeoJSON scalar supports all standard GeoJSON types:

Geometry Objects:

  • Point - Single coordinate
  • LineString - Array of coordinates forming a line
  • Polygon - Array of coordinate arrays forming a polygon
  • MultiPoint - Array of Point coordinates
  • MultiLineString - Array of LineString coordinates
  • MultiPolygon - Array of Polygon coordinates
  • GeometryCollection - Collection of geometry objects

Feature Objects:

  • Feature - Geometry with properties
  • FeatureCollection - Array of features

Common Use Cases

JSON Scalars are commonly used for:

  • Configuration Data: Application settings and preferences
  • Metadata Storage: Flexible key-value data
  • API Responses: Dynamic content that doesn't fit strict schemas
  • User Customization: Personalization data
  • Legacy Data: Migration of unstructured data

GeoJSON is commonly used for:

  • Mapping Applications: Geographic data representation
  • Location Services: Points of interest, routes, boundaries
  • GIS Systems: Geographic information system integration
  • Delivery Services: Service areas and routes
  • Real Estate: Property boundaries and locations

Performance Considerations

  • JSON/JSONObject: Large JSON objects can impact query performance
  • GeoJSON: Complex polygons with many coordinates can be memory-intensive
  • Indexing: Consider database indexing for frequently queried JSON fields
  • Validation: Client-side pre-validation can reduce server load

Type Definitions

// String constants for schema building
const JSON: string;        // "scalar JSON"
const JSONObject: string;  // "scalar JSONObject"  
const GeoJSON: string;     // "scalar GeoJSON"

Mock Data

// Mock data generators for testing
const JSONMock: () => any;
const JSONObjectMock: () => object;
const GeoJSONMock: () => object;

Error Handling

Data format scalars provide specific error messages:

// JSON validation errors
"Value is not valid JSON: invalid-json-string"

// JSONObject validation errors
"Value must be a JSON object, not array or primitive"

// GeoJSON validation errors
"Value is not valid GeoJSON: missing required 'type' property"
"Invalid GeoJSON geometry type: InvalidType"
"Invalid coordinates format for Point geometry"

Security Considerations

When using JSON scalars:

  • Input Validation: Always validate JSON content beyond just format
  • Size Limits: Implement reasonable limits on JSON object size
  • Nested Depth: Consider limiting nesting depth to prevent stack overflow
  • Content Filtering: Sanitize JSON content for security-sensitive applications