Skip to content

Commit ef91d9e

Browse files
wilsonriverawilsonrivera
authored
feat: update the documentation for subgraph schema extensions (#263)
* feat: update the documentation for subgraph schema extensions * chore: fix typo * chore: add `LabelInfo` section
1 parent d1b045a commit ef91d9e

4 files changed

Lines changed: 81 additions & 61 deletions

File tree

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

Lines changed: 28 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -15,18 +15,20 @@ description: "Definition of the Subgraph Check extension payload structure."
1515
|----------------------|--------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
1616
| `subgraphs` | [`SubgraphInfo[]`](#subgraphinfo) or `undefined` | A list of subgraphs that trigger the check. |
1717
| `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. |
2118
| `affectedOperations` | [`AffectedOperationInfo[]`](#affectedoperationinfo) or `undefined` | A list containing all the operations affected by the check. |
2219

2320
## 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` | |
21+
| Field | Type | Description |
22+
|----------------------|------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
23+
| `id` | `string` | The unique identifier of the subgraph. |
24+
| `name` | `string` | The name of the subgraph. |
25+
| `labels` | [`LabelInfo[]`](#labelinfo) | The list of labels the subgraph is associated with. |
26+
| `oldComposedSdl` | `string` or `undefined` | The original subgraph SDL |
27+
| `newComposedSdl` | `string` or `undefined` | The new subgraph SDL |
28+
| `lintIssues` | [`LintIssue[]`](#lintissue) or `undefined` | A list containing all the lint issues detected based on the `Lint Policies`. |
29+
| `graphPruningIssues` | [`GraphPruningIssue[]`](#graphpruningissue) or `undefined` | A list containing all the graph pruning issues detected based on the `Graph Pruning Policies` |
30+
| `schemaChanges` | [`SchemaChangeInfo[]`](#schemachangeinfo) or `undefined` | A list containing all the changes detected by the check. |
31+
3032

3133
## CompositionInfo
3234
| Field | Type | Description |
@@ -37,6 +39,14 @@ description: "Definition of the Subgraph Check extension payload structure."
3739
| `federatedClientSchema` | `string` | The composed schema for the Federated Client. |
3840
| `subgraphs` | [`CompositionSubgraphInfo[]`](#compositionsubgraphinfo) | A collection of all subgraphs that contributed to this composition. |
3941

42+
### LabelInfo
43+
Provides information about the labels associated with the subgraph.
44+
45+
| Field | Type | Description |
46+
|--------|----------|------------------------|
47+
| `key` | `string` | The key of the label. |
48+
| `name` | `string` | The name of the label. |
49+
4050
## CompositionSubgraphInfo
4151
| Field | Type | Description |
4252
|--------|----------|----------------------------------------|
@@ -200,8 +210,17 @@ description: "Definition of the Subgraph Check extension payload structure."
200210
interface SubgraphInfo {
201211
id: string;
202212
name: string;
213+
labels: LabelInfo[];
203214
oldComposedSdl?: string;
204215
newComposedSdl?: string;
216+
lintIssues?: LintIssue[];
217+
graphPruningIssues?: GraphPruningIssue[];
218+
schemaChanges?: SchemaChangeInfo[];
219+
}
220+
221+
interface LabelInfo {
222+
key: string;
223+
name: string;
205224
}
206225

207226
interface CompositionInfo {
@@ -280,9 +299,6 @@ interface AffectedOperationInfo {
280299
interface SubgraphCheckExtensionContent {
281300
subgraphs?: SubgraphInfo[];
282301
compositions?: CompositionInfo;
283-
lintIssues?: LintIssue[];
284-
graphPruningIssues?: GraphPruningIssue[];
285-
schemaChanges?: SchemaChangeInfo[];
286302
affectedOperations?: AffectedOperationInfo[];
287303
}
288304
```

‎docs/studio/sce/handler-example.mdx‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -90,19 +90,22 @@ The following example includes the handler implementation, a helper for validati
9090
}
9191
9292
return {
93-
lintIssues: [
94-
{
95-
lintRuleType: 'TYPE_SUFFIX',
96-
severity: 1,
97-
message: 'Type names should use the prefix `Type`',
98-
issueLocation: {
99-
line: 9,
100-
column: 6,
101-
endLine: 9,
102-
endColumn: 11,
93+
lintIssues: {
94+
// The key is the name of the subgraph the lint issues apply for
95+
'my-subgraph': [
96+
{
97+
lintRuleType: 'TYPE_SUFFIX',
98+
severity: 1,
99+
message: 'Type names should use the prefix `Type`',
100+
issueLocation: {
101+
line: 9,
102+
column: 6,
103+
endLine: 9,
104+
endColumn: 11,
105+
},
103106
},
104-
},
105-
],
107+
]
108+
},
106109
};
107110
},
108111
);
@@ -160,6 +163,7 @@ The following example includes the handler implementation, a helper for validati
160163
161164
export interface SubgraphInfo {
162165
id: string;
166+
labels: LabelInfo[];
163167
name: string;
164168
isDeleted: boolean;
165169
}
@@ -198,13 +202,9 @@ The following example includes the handler implementation, a helper for validati
198202
};
199203
}
200204
201-
export interface OverwriteInfo {
202-
lintIssues: LintIssue[];
203-
}
204-
205205
export interface SubgraphCheckExtensionReply {
206206
errors?: string[];
207-
lintIssues: LintIssue[];
207+
lintIssues?: Record<string, LintIssue[]>;
208208
}
209209
```
210210
</CodeGroup>

‎docs/studio/sce/request-payload-structure.mdx‎

Lines changed: 28 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -32,52 +32,53 @@ is generated and the `url` field will be `undefined` or not present in the reque
3232
### LabelInfo
3333
Provides information about the labels used to trigger the check.
3434

35-
| Field | Type | Description |
36-
|-------|----------|------------------------|
37-
| key | `string` | The key of the label. |
38-
| name | `string` | The name of the label. |
35+
| Field | Type | Description |
36+
|--------|----------|------------------------|
37+
| `key` | `string` | The key of the label. |
38+
| `name` | `string` | The name of the label. |
3939

4040
### OrganizationContext
4141
Provides information about the organization that triggered the check.
4242

43-
| Field | Type | Description |
44-
|-------|----------|--------------------------------------------|
45-
| id | `string` | The unique identifier of the organization. |
46-
| slug | `string` | The slug of the organization. |
43+
| Field | Type | Description |
44+
|--------|----------|--------------------------------------------|
45+
| `id` | `string` | The unique identifier of the organization. |
46+
| `slug` | `string` | The slug of the organization. |
4747

4848
### NamespaceContext
4949
Provides information about the associated namespace.
5050

51-
| Field | Type | Description |
52-
|-------|----------|-----------------------------------------|
53-
| id | `string` | The unique identifier of the namespace. |
54-
| name | `string` | The display name of the namespace. |
51+
| Field | Type | Description |
52+
|--------|----------|-----------------------------------------|
53+
| `id` | `string` | The unique identifier of the namespace. |
54+
| `name` | `string` | The display name of the namespace. |
5555

5656
### VCSContext
5757
Provides details about the Version Control System (VCS) that triggered the check. This field is only included when the check is initiated from a VCS.
5858

59-
| Field | Type | Description |
60-
|-----------|----------|------------------------------------------------------|
61-
| author | `string` | The email address of the commit author. |
62-
| commitSha | `string` | The SHA hash of the commit that triggered the check. |
63-
| branch | `string` | The branch name associated with the commit. |
59+
| Field | Type | Description |
60+
|-------------|----------|------------------------------------------------------|
61+
| `author` | `string` | The email address of the commit author. |
62+
| `commitSha` | `string` | The SHA hash of the commit that triggered the check. |
63+
| `branch` | `string` | The branch name associated with the commit. |
6464

6565
### AffectedGraphInfo
6666
Provides information about the graphs affected by the check.
6767

68-
| Field | Type | Description |
69-
|-------|----------|-------------------------------------|
70-
| id | `string` | The unique identifier of the graph. |
71-
| name | `string` | The name of the graph. |
68+
| Field | Type | Description |
69+
|--------|----------|-------------------------------------|
70+
| `id` | `string` | The unique identifier of the graph. |
71+
| `name` | `string` | The name of the graph. |
7272

7373
### SubgraphContext
7474
Provides information about the subgraphs that triggered the check. This field is only included when the check is for an existing subgraph.
7575

76-
| Field | Type | Description |
77-
|-----------|-----------|------------------------------------------------------------------|
78-
| id | `string` | The unique identifier of the subgraph. |
79-
| name | `string` | The name of the subgraph. |
80-
| isDeleted | `boolean` | Indicates whether the check was triggered by a deleted subgraph. |
76+
| Field | Type | Description |
77+
|-------------|-----------------------------|------------------------------------------------------------------|
78+
| `id` | `string` | The unique identifier of the subgraph. |
79+
| `labels` | [`LabelInfo[]`](#labelinfo) | The list of labels the subgraph is associated with. |
80+
| `name` | `string` | The name of the subgraph. |
81+
| `isDeleted` | `boolean` | Indicates whether the check was triggered by a deleted subgraph. |
8182

8283
## TypeScript definition
8384

@@ -111,6 +112,7 @@ interface AffectedGraphInfo {
111112

112113
interface SubgraphInfo {
113114
id: string;
115+
labels: LabelInfo[];
114116
name: string;
115117
isDeleted: boolean;
116118
}

‎docs/studio/sce/response-structure.mdx‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,18 @@ description: "Definition of the response payload structure for Subgraph Check Ex
88
When your server receives a request from the Subgraph Check Extension, it must respond with either `204 No Content`, which indicates that nothing changed, or `200 OK` with the structure described below.
99

1010
The response payload allows you to append a collection of **LintIssues** to the check, which will be displayed on the
11-
Check results page.
11+
Check results page. To do this, the response must contain the `lintIssues` field with the **subgraph name** as the key
12+
and the **LintIssues** as the value.
13+
1214
You can also return a collection of error messages to be displayed in the extension’s UI.
1315

1416
The response payload must be a JSON object no larger than **5 MB**.
1517

1618
## SubgraphCheckExtensionReply
17-
| Field | Type | Description |
18-
|--------------|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
19-
| `errors` | `string[]` or `undefined` | An optional collection of errors caught by the check extension. When one or more errors are returned, the subgraph check extension reports the result as a failure. |
20-
| `lintIssues` | [`LintIssue[]`](#lintissue) or `undefined` | An optional collection of lint issues that will be appended to the ones reported by the internal lint check. If you only want to see issues reported by your service, disable the `Lint Policies`. |
19+
| Field | Type | Description |
20+
|--------------|----------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
21+
| `errors` | `string[]` or `undefined` | An optional collection of errors caught by the check extension. When one or more errors are returned, the subgraph check extension reports the result as a failure. |
22+
| `lintIssues` | `Record<string, `[`LintIssue[]`](#lintissue)`>` or `undefined` | An optional map of the lint issues by subgraph name that will be appended to the ones reported by the internal lint check. If you only want to see issues reported by your service, disable the `Lint Policies`. |
2123

2224
## LintIssue
2325
| Field | Type | Description |
@@ -65,6 +67,6 @@ enum LintSeverity {
6567

6668
interface SubgraphCheckExtensionReply {
6769
errors?: string[];
68-
lintIssues?: LintIssue[];
70+
lintIssues?: Record<string, LintIssue[]>;
6971
}
7072
```

0 commit comments

Comments
 (0)