Namespacing the schema

Have all types and interfaces added to the schema by plugins be automatically namespaced.

Namespacing the schema avoids naming conflicts, which happens when different owners (eg: different teams in the company, or among 3rd party plugins) use the same name for a type or interface.

For instance, let's say that company "AwesomeWP" has the Tutorials and the Sales team, and both of them create a Product type for the company's GraphQL schema, producing a conflict.

By namespacing the schema, the two types would be automatically converted to AwesomeWPTutorialsProduct and AwesomeWPSalesProduct, avoiding the conflict without having to manually modify the schema, or have the teams interact with each other.

The entities from the WordPress data model are not namespaced permalink

The WordPress data model is considered canonical, and its GraphQL schema types (such as Post and User) and interfaces (such as Commentable and WithMeta) are not namespaced.

Namespacing the schema in the endpoints permalink

There are 2 levels in which we can define if the schema will be namespaced or not. In order of priority:

1. On the schema configuration permalink

Namespacing the schema for a custom endpoint or persisted query, can be defined through the corresponding schema configuration:

2. Default mode, defined in the Settings permalink

If the schema configuration has value "Default", it will use the mode defined in the Settings:

Namespacing the schema in the Admin clients permalink

Namespacing the schema in the wp-admin can be selected on the Settings. It will be applied on the GraphiQL and Interactive Schema clients, on the configuration in Access/Cache Control Lists, and possibly on other extensions.

Visualizing the namespaced schema permalink

Use the Voyager client to visualize the namespaced schema.

When namespacing is disabled, the WordPress schema looks like this:

When it is enabled, the types and interfaces added by plugins are namespaced, looking like this:

Querying (non-)namespaced type names permalink

Once namespaced is enabled, types can be queried using both their namespaced and non-namespaced type names. Hence, only queries involving conflicting types need be edited, and not all of them.

For instance, if AwesomeWP's Sales team also has a Discount type, a query asking for this type name still works:

query {
  discounts {
    ...DiscountProps
  }
}

fragment DiscountProps on Discount {
  price
  dateRange
}

Only the conflicting type Product should be updated to AwesomeWPSalesProduct in the query, as to remove any ambiguity:

query {
  products {
    ...ProductProps
  }
}

fragment ProductProps on AwesomeWPSalesProduct {
  price
  dateRange
}

GraphQL spec permalink

This functionality is currently not part of the GraphQL spec, but it has been requested in:

• issue #163 - Namespaces.

Share