Skip to main content
Version: 🚧 Canary

🔍 Location Schemas

Location schemas provide JSON Schema definitions for location data validation in NodeBlocks applications. These schemas ensure data integrity and provide clear contracts for location-related API endpoints.

🎯 Overview​

Location schemas are designed to:

  • Validate location data before processing
  • Ensure location data consistency across the application
  • Provide clear contracts for location API endpoints
  • Enable type safety with TypeScript integration
  • Support composition with other location blocks
  • Handle hierarchical relationships with parent-child validation

📋 Location Schema Types​

Base Location Schemas​

Core location entity structures used as foundations for other schemas.

Location Creation Schemas​

Schemas for location creation with required field validation and hierarchical parent support.

Location Retrieval Schemas​

Schemas for getting specific locations with identifier validation.

Location Update Schemas​

Schemas for location modifications with optional field validation.

Location Search Schemas​

Schemas for location filtering and pagination parameters.

Location Deletion Schemas​

Schemas for location removal operations.

🔧 Available Location Schemas​

locationSchema​

Location base schema with core properties for location entities.

Purpose: Defines the fundamental structure for all location entities with required and optional fields.

Schema Details:

  • Type: object
  • Properties: code (string), name (string), type (string)
  • Additional Properties: false (strict validation)

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { locationSchema } = schemas;

// Use in schema composition
export const customLocationSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          ...locationSchema,
          required: ['name', 'code', 'type']
        }
      }
    }
  }
});

createLocationSchema​

Location creation schema with required fields validation for new location registration.

Purpose: Validates requests for creating new locations with proper hierarchical parent support and required field validation.

Schema Details:

  • Request Body: required
  • Content-Type: application/json
  • Properties:
    • name: string (required) - Human-readable location name
    • code: string (required) - Unique location identifier code
    • type: string (required) - Location type classification (e.g., 'ORGANIZATION', 'REGION', 'CITY', 'BUILDING')
    • parentId: string (optional) - ID of the parent location for hierarchical relationships
  • Additional Properties: false (strict validation)

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { createLocationSchema } = schemas;

const schema = createLocationSchema({});
const validate = ajv.compile(schema.schemas as SchemaDefinition);
const isValid = validate({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          name: 'Downtown Office',
          code: 'DTO-001',
          type: 'BUILDING',
          parentId: 'city-123'
        }
      }
    }
  }
});

getLocationSchema​

Location retrieval schema with path parameter validation for single location lookup.

Purpose: Validates requests for retrieving individual locations by their IDs with proper path parameter validation.

Schema Details:

  • Parameters: locationId (path parameter, required)
  • Type: Path parameter validation only
  • Request Body: Not applicable (GET request)

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { getLocationSchema } = schemas;

const schema = getLocationSchema({});
const validate = ajv.compile(schema.schemas as SchemaDefinition);
const isValid = validate({
  parameters: [{ locationId: 'loc-123' }]
});

updateLocationSchema​

Location update schema with optional fields validation for partial location updates.

Purpose: Validates requests for updating existing locations with partial field modifications, supporting flexible update operations.

Schema Details:

  • Parameters: locationId (path parameter, required)
  • Request Body: required
  • Content-Type: application/json
  • Properties:
    • name: string (optional) - Human-readable location name
    • code: string (optional) - Unique location identifier code
    • type: string (optional) - Location type classification
  • Additional Properties: false (strict validation)

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { updateLocationSchema } = schemas;

const schema = updateLocationSchema({});
const validate = ajv.compile(schema.schemas as SchemaDefinition);
const isValid = validate({
  parameters: [{ locationId: 'loc-123' }],
  requestBody: {
    content: {
      'application/json': {
        schema: {
          name: 'Updated Name'
        }
      }
    }
  }
});

deleteLocationSchema​

Location deletion schema with path parameter validation for location removal.

Purpose: Validates requests for deleting existing locations with proper path parameter validation and security constraints.

Schema Details:

  • Parameters: locationId (path parameter, required)
  • Type: Path parameter validation only
  • Request Body: Not applicable (DELETE request)

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { deleteLocationSchema } = schemas;

const schema = deleteLocationSchema({});
const validate = ajv.compile(schema.schemas as SchemaDefinition);
const isValid = validate({
  parameters: [{ locationId: 'loc-123' }]
});

findLocationsSchema​

Location search schema with pagination query validation.

Purpose: Validates requests for searching and listing locations with pagination parameters, providing a foundation for extensible location discovery.

Schema Details:

  • Type: Query parameter validation only
  • Query Parameters: page (optional, 1-1000), limit (optional, 1-50)
  • Request Body: Not applicable (GET request)

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { findLocationsSchema } = schemas;

const schema = findLocationsSchema({});
const validate = ajv.compile(schema.schemas as SchemaDefinition);
const isValid = validate({
  parameters: [
    { in: 'query', name: 'page', value: 2 },
    { in: 'query', name: 'limit', value: 20 }
  ]
});

🔗 Related Documentation​