Skip to content

Commit a9a1e87

Browse files
wilsonriveraBrendanBondurant
wilsonrivera
and
BrendanBondurant
authored
feat: add documentation for subgraph check extensions (#181)
* feat: add documentation for subgraph check extensions * chore: improve documentation * chore: update documentation * Brendan editing * chore: update image and formatting * chore: add use cases --------- Co-authored-by: Brendan Bondurant <[email protected]>
1 parent 6e332b8 commit a9a1e87

File tree

7 files changed

+814
-0
lines changed

7 files changed

+814
-0
lines changed

‎docs/docs.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -267,6 +267,17 @@
267267
"studio/schema-explorer",
268268
"studio/schema-registry",
269269
"studio/schema-checks",
270+
{
271+
"group": "Check Extensions",
272+
"icon": "puzzle-piece-simple",
273+
"pages": [
274+
"studio/subgraph-check-extensions",
275+
"studio/sce/request-payload-structure",
276+
"studio/sce/response-structure",
277+
"studio/sce/file-content",
278+
"studio/sce/handler-example"
279+
]
280+
},
270281
"studio/schema-contracts",
271282
"studio/overrides",
272283
"studio/changelog",

‎docs/images/studio/sce/config.png‎

99.1 KB
Loading

‎docs/studio/sce/file-content.mdx‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
---
2+
title: "File Structure"
3+
sidebarTitle: File Structure
4+
icon: file-export
5+
description: "Definition of the Subgraph Check extension payload structure."
6+
---
7+
8+
## SubgraphCheckExtensionContent
9+
<Note>
10+
The fields listed below are all optional and can be included or excluded based on the
11+
[namespace configuration](/studio/subgraph-check-extensions#configuration).
12+
</Note>
13+
14+
| Field | Type | Description |
15+
|----------------------|--------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
16+
| `subgraphs` | [`SubgraphInfo[]`](#subgraphinfo) or `undefined` | A list of subgraphs that trigger the check. |
17+
| `compositions` | [`CompositionInfo[]`](#compositioninfo) or `undefined` | A list of all compositions produced by the check. |
18+
| `lintIssues` | [`LintIssues[]`](#lintissue) or `undefined` | A list containing all the lint issues detected based on the `Lint Policies`. |
19+
| `graphPruningIssues` | [`GraphPruningIssues[]`](#graphpruningissue) or `undefined` | A list containing all the graph pruning issues detected based on the `Graph Pruning Policies` |
20+
| `schemaChanges` | [`SchemaChangeInfo[]`](#schemachangeinfo) or `undefined` | A list containing all the changes detected by the check. |
21+
| `affectedOperations` | [`AffectedOperationInfo[]`](#affectedoperationinfo) or `undefined` | A list containing all the operations affected by the check. |
22+
23+
## SubgraphInfo
24+
| Field | Type | Description |
25+
|------------------|-------------------------|----------------------------------------|
26+
| `id` | `string` | The unique identifier of the subgraph. |
27+
| `name` | `string` | The name of the subgraph. |
28+
| `oldComposedSdl` | `string` or `undefined` | |
29+
| `newComposedSdl` | `string` or `undefined` | |
30+
31+
## CompositionInfo
32+
| Field | Type | Description |
33+
|-------------------------|---------------------------------------------------------|---------------------------------------------------------------------|
34+
| `id` | `string` | The unique identifier of the composition. |
35+
| `name` | `string` | The name of the composition. |
36+
| `composedSchema` | `string` | The composed SDL schema. |
37+
| `federatedClientSchema` | `string` | The composed schema for the Federated Client. |
38+
| `subgraphs` | [`CompositionSubgraphInfo[]`](#compositionsubgraphinfo) | A collection of all subgraphs that contributed to this composition. |
39+
40+
## CompositionSubgraphInfo
41+
| Field | Type | Description |
42+
|--------|----------|----------------------------------------|
43+
| `id` | `string` | The unique identifier of the subgraph. |
44+
| `name` | `string` | The name of the subgraph. |
45+
| `sdl` | `string` | The SDL of the subgraph. |
46+
47+
## LintIssue
48+
| Field | Type | Description |
49+
|-----------------|-------------------------------------------|-----------------------------------------------------------|
50+
| `lintRuleType` | `string` | One of the [lint rule](/studio/lint-policy/linter-rules). |
51+
| `severity` | [`LintSeverity`](#lintseverity) | The severity of the issue. |
52+
| `message` | `string` | A message describing the issue. |
53+
| `issueLocation` | [`LintIssueLocation`](#lintissuelocation) | The location of the issue related to the schema. |
54+
55+
## LintSeverity
56+
| Field | Value | Description |
57+
|---------|-------|----------------------------|
58+
| Warning | `0` | Represents a lint warning. |
59+
| Error | `1` | Represents a lint error. |
60+
61+
## LintIssueLocation
62+
| Field | Type | Description |
63+
|-------------|-------------------------|------------------------------------------|
64+
| `line` | `number` | The line number of the lint issue. |
65+
| `column` | `number` | The column number of the lint issue. |
66+
| `endLine` | `number` or `undefined` | The end line number of the lint issue. |
67+
| `endColumn` | `number` or `undefined` | The end column number of the lint issue. |
68+
69+
## GraphPruningIssue
70+
| Field | Type | Description |
71+
|------------------------|-----------------------------------------------------------|--------------------------------------------------|
72+
| `graphPruningRuleType` | [`GraphPruningRuleType`](#graphpruningruletype) | The graph pruning rule. |
73+
| `severity` | [`GraphPruningSeverity`](#graphpruningseverity) | The severity of the issue. |
74+
| `fieldPath` | `string` | The path to the field. |
75+
| `message` | `string` | A message describing the issue. |
76+
| `issueLocation` | [`GraphPruningIssueLocation`](#graphpruningissuelocation) | The location of the issue related to the schema. |
77+
| `federatedGraphId` | `string` | The unique identifier of the Federated graph. |
78+
| `federatedGraphName` | `string` | The name of the Federated graph. |
79+
| `subgraphName` | `string` or `undefined` | The name of the subgraph. |
80+
81+
## GraphPruningRuleType
82+
| Value | Description |
83+
|---------------------------------------|----------------------------------------------------------------|
84+
| `UNUSED_FIELDS` | Represents a graph pruning issue related to a federated graph. |
85+
| `DEPRECATED_FIELDS` | Represents a graph pruning issue related to a subgraph. |
86+
| `REQUIRE_DEPRECATION_BEFORE_DELETION` | Represents a graph pruning issue related to a subgraph. |
87+
88+
## GraphPruningSeverity
89+
| Field | Value | Description |
90+
|---------|-------|-------------------------------------|
91+
| Warning | `0` | Represents a graph pruning warning. |
92+
| Error | `1` | Represents a graph pruning error. |
93+
94+
## GraphPruningIssueLocation
95+
| Field | Type | Description |
96+
|-------------|-------------------------|---------------------------------------------------|
97+
| `line` | `number` | The line number of the graph pruning issue. |
98+
| `column` | `number` | The column number of the graph pruning issue. |
99+
| `endLine` | `number` or `undefined` | The end line number of the graph pruning issue. |
100+
| `endColumn` | `number` or `undefined` | The end column number of the graph pruning issue. |
101+
102+
## SchemaChangeInfo
103+
| Field | Type | Description |
104+
|--------------|-----------|--------------------------------------------------------------------------------------------------------------------|
105+
| `message` | `string` | A `string` representation of the change. |
106+
| `changeType` | `string` | A string representing the type of change. You can find the possible values [here](#list-of-possible-change-types). |
107+
| `path` | `string` | The path to the schema change. |
108+
| `isBreaking` | `boolean` | A value indicating whether the detected change is considered breaking or not. |
109+
110+
### List of possible change types
111+
- FIELD_ARGUMENT_DESCRIPTION_CHANGED
112+
- FIELD_ARGUMENT_DEFAULT_CHANGED
113+
- FIELD_ARGUMENT_TYPE_CHANGED
114+
- DIRECTIVE_REMOVED
115+
- DIRECTIVE_ADDED
116+
- DIRECTIVE_DESCRIPTION_CHANGED
117+
- DIRECTIVE_LOCATION_ADDED
118+
- DIRECTIVE_LOCATION_REMOVED
119+
- DIRECTIVE_ARGUMENT_ADDED
120+
- DIRECTIVE_ARGUMENT_REMOVED
121+
- DIRECTIVE_ARGUMENT_DESCRIPTION_CHANGED
122+
- DIRECTIVE_ARGUMENT_DEFAULT_VALUE_CHANGED
123+
- DIRECTIVE_ARGUMENT_TYPE_CHANGED
124+
- ENUM_VALUE_REMOVED
125+
- ENUM_VALUE_ADDED
126+
- ENUM_VALUE_DESCRIPTION_CHANGED
127+
- ENUM_VALUE_DEPRECATION_REASON_CHANGED
128+
- ENUM_VALUE_DEPRECATION_REASON_ADDED
129+
- ENUM_VALUE_DEPRECATION_REASON_REMOVED
130+
- FIELD_REMOVED
131+
- FIELD_ADDED
132+
- FIELD_DESCRIPTION_CHANGED
133+
- FIELD_DESCRIPTION_ADDED
134+
- FIELD_DESCRIPTION_REMOVED
135+
- FIELD_DEPRECATION_ADDED
136+
- FIELD_DEPRECATION_REMOVED
137+
- FIELD_DEPRECATION_REASON_CHANGED
138+
- FIELD_DEPRECATION_REASON_ADDED
139+
- FIELD_DEPRECATION_REASON_REMOVED
140+
- FIELD_TYPE_CHANGED
141+
- FIELD_ARGUMENT_ADDED
142+
- FIELD_ARGUMENT_REMOVED
143+
- INPUT_FIELD_REMOVED
144+
- INPUT_FIELD_ADDED
145+
- INPUT_FIELD_DESCRIPTION_ADDED
146+
- INPUT_FIELD_DESCRIPTION_REMOVED
147+
- INPUT_FIELD_DESCRIPTION_CHANGED
148+
- INPUT_FIELD_DEFAULT_VALUE_CHANGED
149+
- INPUT_FIELD_TYPE_CHANGED
150+
- OBJECT_TYPE_INTERFACE_ADDED
151+
- OBJECT_TYPE_INTERFACE_REMOVED
152+
- SCHEMA_QUERY_TYPE_CHANGED
153+
- SCHEMA_MUTATION_TYPE_CHANGED
154+
- SCHEMA_SUBSCRIPTION_TYPE_CHANGED
155+
- TYPE_REMOVED
156+
- TYPE_ADDED
157+
- TYPE_KIND_CHANGED
158+
- TYPE_DESCRIPTION_CHANGED
159+
- TYPE_DESCRIPTION_REMOVED
160+
- TYPE_DESCRIPTION_ADDED
161+
- UNION_MEMBER_REMOVED
162+
- UNION_MEMBER_ADDED
163+
- DIRECTIVE_USAGE_UNION_MEMBER_ADDED
164+
- DIRECTIVE_USAGE_UNION_MEMBER_REMOVED
165+
- DIRECTIVE_USAGE_ENUM_ADDED
166+
- DIRECTIVE_USAGE_ENUM_REMOVED
167+
- DIRECTIVE_USAGE_ENUM_VALUE_ADDED
168+
- DIRECTIVE_USAGE_ENUM_VALUE_REMOVED
169+
- DIRECTIVE_USAGE_INPUT_OBJECT_ADDED
170+
- DIRECTIVE_USAGE_INPUT_OBJECT_REMOVED
171+
- DIRECTIVE_USAGE_FIELD_ADDED
172+
- DIRECTIVE_USAGE_FIELD_REMOVED
173+
- DIRECTIVE_USAGE_SCALAR_ADDED
174+
- DIRECTIVE_USAGE_SCALAR_REMOVED
175+
- DIRECTIVE_USAGE_OBJECT_ADDED
176+
- DIRECTIVE_USAGE_OBJECT_REMOVED
177+
- DIRECTIVE_USAGE_INTERFACE_ADDED
178+
- DIRECTIVE_USAGE_INTERFACE_REMOVED
179+
- DIRECTIVE_USAGE_ARGUMENT_DEFINITION_ADDED
180+
- DIRECTIVE_USAGE_ARGUMENT_DEFINITION_REMOVED
181+
- DIRECTIVE_USAGE_SCHEMA_ADDED
182+
- DIRECTIVE_USAGE_SCHEMA_REMOVED
183+
- DIRECTIVE_USAGE_FIELD_DEFINITION_ADDED
184+
- DIRECTIVE_USAGE_FIELD_DEFINITION_REMOVED
185+
- DIRECTIVE_USAGE_INPUT_FIELD_DEFINITION_ADDED
186+
- DIRECTIVE_USAGE_INPUT_FIELD_DEFINITION_REMOVED
187+
188+
## AffectedOperationInfo
189+
| Field | Type | Description |
190+
|------------------|------------|------------------------------------------------------------------------------|
191+
| `schemaChangeId` | `string` | The unique identifier of the schema change. |
192+
| `hash` | `string` | The unique hash of the operation. |
193+
| `name` | `string` | The name of the operation. |
194+
| `type` | `string` | The type of the operation. |
195+
| `firstSeenAt` | `ISO Date` | A `Date` with the `ISO` format indicating when the operation was first seen. |
196+
| `lastSeenAt` | `ISO Date` | A `Date` with the `ISO` format indicating when the operation was last seen. |
197+
| `isSafeOverride` | `boolean` | A value indicating whether it is safe for the operation to be overridden. |
198+
199+
```typescript
200+
interface SubgraphInfo {
201+
id: string;
202+
name: string;
203+
oldComposedSdl?: string;
204+
newComposedSdl?: string;
205+
}
206+
207+
interface CompositionInfo {
208+
id: string;
209+
name: string;
210+
composedSchema?: string;
211+
federatedClientSchema?: string;
212+
subgraphs: CompositionSubgraphInfo[];
213+
}
214+
215+
interface CompositionSubgraphInfo {
216+
id: string;
217+
name: string;
218+
sdl: string;
219+
}
220+
221+
interface LintIssue {
222+
lintRuleType: string;
223+
severity: LintSeverity;
224+
message: string;
225+
issueLocation: LintIssueLocation;
226+
}
227+
228+
interface LintIssueLocation {
229+
line: number;
230+
column: number;
231+
endLine?: number;
232+
endColumn?: number;
233+
}
234+
235+
enum LintSeverity {
236+
Warning = 0,
237+
Error = 1
238+
}
239+
240+
interface GraphPruningIssue {
241+
graphPruningRuleType: string;
242+
severity: GraphPruningSeverity;
243+
fieldPath: string;
244+
message: string;
245+
issueLocation: GraphPruningIssueLocation;
246+
federatedGraphId: string;
247+
federatedGraphName: string;
248+
subgraphName?: string;
249+
}
250+
251+
interface GraphPruningIssueLocation {
252+
line: number;
253+
column: number;
254+
endLine?: number;
255+
endColumn?: number;
256+
}
257+
258+
enum GraphPruningSeverity {
259+
Warning = 0,
260+
Error = 1
261+
}
262+
263+
interface SchemaChangeInfo {
264+
message: string;
265+
changeType: string;
266+
path: string;
267+
isBreaking: boolean;
268+
}
269+
270+
interface AffectedOperationInfo {
271+
schemaChangeId: string;
272+
hash: string;
273+
name: string;
274+
type: string;
275+
lastSeenAt: Date;
276+
firstSeenAt: Date;
277+
isSafeOverride: boolean;
278+
}
279+
280+
interface SubgraphCheckExtensionContent {
281+
subgraphs?: SubgraphInfo[];
282+
compositions?: CompositionInfo;
283+
lintIssues?: LintIssue[];
284+
graphPruningIssues?: GraphPruningIssue[];
285+
schemaChanges?: SchemaChangeInfo[];
286+
affectedOperations?: AffectedOperationInfo[];
287+
}
288+
```

0 commit comments

Comments
 (0)