Schema Command

Schema Command

Overview

The schema command displays information about the GraphQL schema used by Graphman, including available entity types and their plural names. It can also refresh the pre-compiled schema metadata.

Syntax

graphman schema [--refresh true|false]
  [--options.<name> <value>,...]

Parameters

Optional Parameters

Parameter	Description	Default
--refresh	Refresh the pre-compiled schema	false
--options.refresh	Alternative way to specify refresh	false

Behavior

Display Mode (Default)

When run without parameters, displays:

• Current schema version
• List of available entity types
• Entity type plural names
• Deprecated entity types (if any)

Refresh Mode

When --refresh true is specified:

• Reprocesses GraphQL schema files
• Regenerates metadata.json
• Updates entity type information
• Refreshes field definitions

Output Information

The command displays:

Information	Description
Schema Version	Current GraphQL schema version (e.g., v11.2.0)
Entity Types	All available entity types
Plural Names	Plural form used in bundles and commands
Deprecated Status	Indicates if entity type is deprecated

Examples

Display Schema Information

View current schema details:

graphman schema

Sample Output:

info: schema v11.2.0
info: available entity types:
         AdministrativeUserAccountProperty - administrativeUserAccountProperties
         AuditConfiguration - auditConfigurations
         ClusterProperty - clusterProperties
         EmailListener - emailListeners
         EncapsulatedAssertion - encassConfigs
         Folder - folders
         InternalUser - internalUsers
         JdbcConnection - jdbcConnections
         JmsDestination - jmsDestinations
         Key - keys
         Policy - policies
         PolicyFragment - policyFragments
         ScheduledTask - scheduledTasks
         Service - services
         ServerModuleFile - serverModuleFiles
         TrustedCert - trustedCerts
         ...

Refresh Schema

Refresh the pre-compiled schema:

graphman schema --refresh true

Output:

info: pre-compiled schema is refreshed
info: schema v11.2.0
info: available entity types:
         ...

Using Options Parameter

Alternative refresh syntax:

graphman schema --options.refresh true

Use Cases

1. Discover Entity Types

Find available entity types for use in commands:

graphman schema

Use the plural names in commands like slice, export, and mappings.

2. Verify Schema Version

Check which schema version is active:

graphman schema

3. Schema Development

Refresh schema after modifying GraphQL files:

# After editing schema files
graphman schema --refresh true

4. Troubleshooting

Verify entity type names when commands fail:

# Check correct plural name
graphman schema | grep -i "service"

5. Documentation

Generate entity type reference:

graphman schema > entity-types.txt

6. Script Integration

Use in scripts to validate entity types:

#!/bin/bash
# Check if entity type exists
if graphman schema | grep -q "services"; then
  echo "Services entity type is available"
fi

Entity Type Information

Entity Type Format

Each entity type is displayed as:

<TypeName> - <pluralName> [status]

Examples:

• Service - services
• Policy - policies
• ClusterProperty - clusterProperties
• OldEntityType - oldEntityTypes (deprecated)

Common Entity Types

Type Name	Plural Name	Description
Service	services	Web Services
Policy	policies	Policies
PolicyFragment	policyFragments	Policy Fragments
Folder	folders	Folders
Key	keys	Private Keys
TrustedCert	trustedCerts	Trusted Certificates
JdbcConnection	jdbcConnections	JDBC Connections
JmsDestination	jmsDestinations	JMS Destinations
ClusterProperty	clusterProperties	Cluster Properties
ScheduledTask	scheduledTasks	Scheduled Tasks
EncapsulatedAssertion	encassConfigs	Encapsulated Assertions
InternalUser	internalUsers	Internal Users
InternalGroup	internalGroups	Internal Groups
ServerModuleFile	serverModuleFiles	Server Module Files

Schema Versions

Supported Versions

Check supported schema versions:

graphman version

Shows:

• Current schema version
• All supported schema versions

Changing Schema Version

Configure in graphman.configuration:

{
  "options": {
    "schema": "v11.1.1"
  }
}

Or specify on command line:

graphman export --options.schema v11.1.1 --gateway dev --output export.json

Schema Files

Location

Schema files are located in:

<graphman-home>/schema/<version>/
├── schema.graphql          # GraphQL schema definition
├── metadata.json           # Pre-compiled metadata
├── policy-code-schema.json # Policy code schema
└── metadata-base.json      # Base metadata

Metadata File

The metadata.json file contains:

• Entity type definitions
• Field information
• Type relationships
• Query and mutation definitions

Refresh Operation

When to Refresh

Refresh the schema when:

• GraphQL schema files are modified
• Custom entity types are added
• Schema definitions are updated
• Troubleshooting schema issues

What Gets Refreshed

• Entity type metadata
• Field definitions
• Type relationships
• Query structures
• Mutation structures

Refresh Process

1. Reads GraphQL schema files
2. Parses type definitions
3. Generates metadata
4. Writes to metadata.json
5. Validates schema structure

Important Notes

• Schema Version: Determined by configuration or default
• Plural Names: Used in bundle JSON and command parameters
• Case Sensitive: Entity type names are case-sensitive
• Deprecated Types: Marked but still available for compatibility
• Read-Only Display: Default mode doesn't modify anything
• Refresh Required: Only needed after schema file changes
• Multiple Versions: Different schema versions may have different entity types

Related Commands

• version: View supported schema versions
• describe: View query and mutation details
• slice: Use entity type plural names
• export: Export specific entity types

Best Practices

1. Check schema before using entity types in commands
2. Use correct plural names from schema output
3. Refresh after schema modifications during development
4. Document entity types used in automation scripts
5. Verify schema version when troubleshooting
6. Keep schema version consistent across environments
7. Review deprecated types before using them

Workflow Examples

Entity Type Discovery

#!/bin/bash
# Find entity type for services
echo "Looking for service entity types:"
graphman schema | grep -i service

# Output:
# Service - services
# ServerModuleFile - serverModuleFiles

Schema Version Check

#!/bin/bash
# Check current schema version
SCHEMA_VERSION=$(graphman schema | grep "schema" | awk '{print $3}')
echo "Current schema version: $SCHEMA_VERSION"

# Verify it matches expected version
if [ "$SCHEMA_VERSION" = "v11.2.0" ]; then
  echo "Schema version is correct"
else
  echo "Warning: Unexpected schema version"
fi

Entity Type Validation

#!/bin/bash
# Validate entity types before using in script
ENTITY_TYPES=("services" "policies" "folders")

for type in "${ENTITY_TYPES[@]}"; do
  if graphman schema | grep -q " $type\$"; then
    echo "✓ $type is valid"
  else
    echo "✗ $type is not found in schema"
  fi
done

Troubleshooting

Unknown Entity Type Error

If commands fail with unknown entity type:

# Check correct plural name
graphman schema | grep -i "<entity-name>"

Schema Version Mismatch

If schema seems incorrect:

# Check configured version
graphman version

# Refresh schema
graphman schema --refresh true

Missing Entity Types

If expected entity types are missing:

• Verify schema version supports the entity type
• Check if entity type is deprecated
• Ensure correct schema version is configured
• Try refreshing the schema

Advanced Usage

Filter Entity Types

# Show only service-related types
graphman schema | grep -i service

# Show only policy-related types
graphman schema | grep -i policy

# Show deprecated types
graphman schema | grep deprecated

Export Entity Type List

# Export to file
graphman schema > entity-types.txt

# Export only entity names
graphman schema | grep "         " | awk '{print $3}' > entity-names.txt

Schema Comparison

# Compare schemas between versions
graphman schema --options.schema v11.1.1 > schema-v11.1.1.txt
graphman schema --options.schema v11.2.0 > schema-v11.2.0.txt
diff schema-v11.1.1.txt schema-v11.2.0.txt

Schema Features by Version

Different schema versions support different features:

Feature	v11.0.00	v11.1.1	v11.2.0
Mappings	✓	✓	✓
Mappings Source	✗	✓	✓
Policy as Code	✗	✓	✓

Check feature support:

graphman version