# 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

```bash
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:

```bash
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:

```bash
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:

```bash
graphman schema --options.refresh true
```

## Use Cases

### 1. Discover Entity Types

Find available entity types for use in commands:

```bash
graphman schema
```

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

### 2. Verify Schema Version

Check which schema version is active:

```bash
graphman schema
```

### 3. Schema Development

Refresh schema after modifying GraphQL files:

```bash
# After editing schema files
graphman schema --refresh true
```

### 4. Troubleshooting

Verify entity type names when commands fail:

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

### 5. Documentation

Generate entity type reference:

```bash
graphman schema > entity-types.txt
```

### 6. Script Integration

Use in scripts to validate entity types:

```bash
#!/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:

```bash
graphman version
```

Shows:
- Current schema version
- All supported schema versions

### Changing Schema Version

Configure in `graphman.configuration`:

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

Or specify on command line:

```bash
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](Version-Command.md)**: View supported schema versions
- **[describe](Describe-Command.md)**: View query and mutation details
- **[slice](Slice-Command.md)**: Use entity type plural names
- **[export](Export-Command.md)**: 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

```bash
#!/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

```bash
#!/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

```bash
#!/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:

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

### Schema Version Mismatch

If schema seems incorrect:

```bash
# 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

```bash
# 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

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

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

### Schema Comparison

```bash
# 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:

```bash
graphman version
```