Skip to content

Commit 9fb12fb

Browse files
grokifyclaude
grokify
and
claude
committed
chore(profiles): add vendor API style profiles for reference
Add comprehensive API style profiles derived from industry guidelines: microsoft-graph/: Microsoft Graph API guidelines microsoft-rest/: Microsoft REST API guidelines omniagent-rest/: OmniAgent REST API guidelines paypal-rest/: PayPal REST API guidelines plexusone-rest/: PlexusOne REST API guidelines zalando-rest/: Zalando RESTful API guidelines Each profile includes: - *.api-style.json: Full specification with rules, patterns, principles - *.api-style.md: Generated Markdown documentation - *.spectral.yaml: Generated Spectral ruleset for linting - *.rubric.json: Generated structured-evaluation rubric - *.evaluation.{json,md,txt}: Sample evaluation outputs These profiles demonstrate the extended type definitions and serve as reference implementations for creating custom organization profiles. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 9ca05cc commit 9fb12fb

38 files changed

Lines changed: 22352 additions & 0 deletions

‎profiles/microsoft-graph/microsoft-graph.api-style.json‎

Lines changed: 1616 additions & 0 deletions
Large diffs are not rendered by default.

‎profiles/microsoft-graph/microsoft-graph.api-style.md‎

Lines changed: 1346 additions & 0 deletions
Large diffs are not rendered by default.

‎profiles/microsoft-graph/microsoft-graph.evaluation.json‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
{
2+
"$schema": "https://raw.githubusercontent.com/grokify/structured-evaluation/main/schema/rubric.schema.json",
3+
"metadata": {
4+
"document": "profiles/microsoft-graph/microsoft-graph.api-style.json",
5+
"documentTitle": "Microsoft Graph API Guidelines",
6+
"generatedAt": "2025-06-17T00:00:00Z",
7+
"generatedBy": "Claude Opus 4.5 (LLM-as-Judge)"
8+
},
9+
"reviewType": "style-guide-quality",
10+
"rubricId": "api-style-guide-quality",
11+
"rubricVersion": "1.0.0",
12+
"categories": [
13+
{
14+
"category": "Content Coverage",
15+
"score": "pass",
16+
"numericScore": 4,
17+
"reasoning": "Covers essential domains with Graph-specific focus: OData-based REST, camelCase naming, /me alias, permissions model with delegated/application scopes, v1.0/beta versioning. Strong on Graph-unique patterns (delta queries, batch, webhooks). Inherits base rules from MS REST.",
18+
"findings": [
19+
{"severity": "low", "category": "Content Coverage", "finding": "Some inherited MS REST topics could be cross-referenced more explicitly", "recommendation": "Add explicit cross-references to base MS REST guide for inherited patterns"}
20+
]
21+
},
22+
{
23+
"category": "Structure & Navigation",
24+
"score": "pass",
25+
"numericScore": 5,
26+
"reasoning": "Excellent structure: TOC, GRAPH-XXX rule IDs, 12 categories focused on Graph-specific topics. Clear navigation between delta, batch, and webhook sections. Well-defined conformance levels.",
27+
"findings": []
28+
},
29+
{
30+
"category": "Rule Quality & Clarity",
31+
"score": "pass",
32+
"numericScore": 4,
33+
"reasoning": "Rules well-structured with IDs, titles, severity, descriptions. Good examples in delta query and batch patterns. RFC 2119 keywords used appropriately.",
34+
"findings": [
35+
{"severity": "low", "category": "Rule Quality & Clarity", "finding": "Some rules have brief descriptions", "recommendation": "Expand rule descriptions with more implementation context and rationale"}
36+
]
37+
},
38+
{
39+
"category": "Examples & Code Samples",
40+
"score": "pass",
41+
"numericScore": 5,
42+
"reasoning": "Excellent examples for Graph-specific patterns: delta query flows with mermaid diagrams, batch request/response JSON, webhook subscription examples. Delta query documentation is particularly well-illustrated.",
43+
"findings": []
44+
},
45+
{
46+
"category": "Enforceability & Tooling",
47+
"score": "partial",
48+
"numericScore": 3,
49+
"reasoning": "Rules distinguish between lintable and judge-only. However, Graph-specific rules are harder to lint than generic REST rules. OData compliance and permission requirements often need manual review.",
50+
"findings": [
51+
{"severity": "medium", "category": "Enforceability & Tooling", "finding": "Many Graph-specific rules require manual/LLM review rather than linting", "recommendation": "Develop Graph-specific Spectral rules where possible; consider OData-aware validators"}
52+
]
53+
},
54+
{
55+
"category": "Guide Versioning & Evolution",
56+
"score": "pass",
57+
"numericScore": 4,
58+
"reasoning": "Guide has versioning and tracks changes. The v1.0/beta versioning model is clearly documented. Change tracking for the guide itself is present.",
59+
"findings": [
60+
{"severity": "low", "category": "Guide Versioning & Evolution", "finding": "Beta to v1.0 migration guidance could be expanded", "recommendation": "Add detailed migration guidance for promoting APIs from beta to v1.0"}
61+
]
62+
},
63+
{
64+
"category": "Completeness & Depth",
65+
"score": "pass",
66+
"numericScore": 4,
67+
"reasoning": "Good depth on Graph-specific topics: delta queries with full flow documentation, batch request semantics, permission scopes, throttling patterns. Some advanced scenarios could use more detail.",
68+
"findings": []
69+
},
70+
{
71+
"category": "Internal Consistency",
72+
"score": "pass",
73+
"numericScore": 5,
74+
"reasoning": "Internally consistent with Graph API conventions. Terminology aligns with OData standards (@odata.context, @odata.deltaLink). Consistent use of /me alias pattern throughout. No contradictions.",
75+
"findings": []
76+
},
77+
{
78+
"category": "Accessibility & Tone",
79+
"score": "pass",
80+
"numericScore": 4,
81+
"reasoning": "Written for developers familiar with Microsoft Graph. Good glossary with 12 Graph-specific terms. Professional tone. Assumes some OData knowledge which is appropriate for the audience.",
82+
"findings": []
83+
}
84+
],
85+
"findings": [
86+
{"severity": "medium", "category": "Enforceability & Tooling", "finding": "Many Graph-specific rules require manual/LLM review rather than linting"},
87+
{"severity": "low", "category": "Content Coverage", "finding": "Some inherited MS REST topics could be cross-referenced more explicitly"},
88+
{"severity": "low", "category": "Rule Quality & Clarity", "finding": "Some rules have brief descriptions; more detail would help"},
89+
{"severity": "low", "category": "Guide Versioning & Evolution", "finding": "Beta to v1.0 migration guidance could be expanded"}
90+
],
91+
"passCriteria": {
92+
"minCategoriesPassing": "all_required",
93+
"maxFindings": {"critical": 0, "high": 2, "medium": 5}
94+
},
95+
"decision": {
96+
"status": "pass",
97+
"reasoning": "All 9 categories pass (5 excellent, 4 good, 1 acceptable). Only 1 medium-severity and 3 low-severity findings.",
98+
"categoryCounts": {"pass": 8, "partial": 1, "fail": 0, "total": 9},
99+
"findingCounts": {"critical": 0, "high": 0, "medium": 1, "low": 3, "total": 4}
100+
},
101+
"overallDecision": "pass",
102+
"nextSteps": {
103+
"immediate": [],
104+
"recommended": [
105+
{"action": "Develop Graph-specific Spectral rules for OData patterns", "category": "Enforceability & Tooling", "effort": "high"},
106+
{"action": "Add explicit cross-references to base MS REST guide", "category": "Content Coverage", "effort": "low"},
107+
{"action": "Expand rule descriptions with implementation context", "category": "Rule Quality & Clarity", "effort": "medium"},
108+
{"action": "Add beta-to-v1.0 API promotion migration guide", "category": "Guide Versioning & Evolution", "effort": "medium"}
109+
]
110+
},
111+
"summary": "Microsoft Graph API Guidelines: 4/5 overall. Solid specialized guide with 82 rules tailored for the Graph unified API model. Excels in OData patterns, delta queries, and Graph-specific conventions. Improvements: develop Graph-specific Spectral rules, expand rule descriptions, add migration guidance."
112+
}

‎profiles/microsoft-graph/microsoft-graph.evaluation.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
## Evaluation Report: Microsoft Graph API Guidelines
2+
3+
### Summary
4+
5+
**Overall Decision: PASS** ✅
6+
7+
| Metric | Value |
8+
|--------|-------|
9+
| Categories | 8 pass, 1 partial, 0 fail |
10+
| Findings | 0 critical, 0 high, 1 medium |
11+
| Decision | Pass |
12+
13+
---
14+
15+
### Metadata
16+
17+
- **Document**: profiles/microsoft-graph/microsoft-graph.api-style.json
18+
- **Title**: Microsoft Graph API Guidelines
19+
- **Rubric**: api-style-guide-quality v1.0.0
20+
- **Review Type**: style-guide-quality
21+
- **Generated**: 2025-06-17 00:00:00 UTC
22+
23+
---
24+
25+
### Category Results
26+
27+
| Category | Score | Weight | Required | Reasoning |
28+
|----------|-------|--------|----------|----------|
29+
| **Content Coverage** | 4/5 🟡 | - | | Covers essential domains with Graph-specific focus: OData... |
30+
| **Structure & Navigation** | 5/5 🟢 | - | | Excellent structure: TOC, GRAPH-XXX rule IDs, 12 categori... |
31+
| **Rule Quality & Clarity** | 4/5 🟡 | - | | Rules well-structured with IDs, titles, severity, descrip... |
32+
| **Examples & Code Samples** | 5/5 🟢 | - | | Excellent examples for Graph-specific patterns: delta que... |
33+
| **Enforceability & Tooling** | 3/5 🟡 | - | | Rules distinguish between lintable and judge-only. Howeve... |
34+
| **Guide Versioning & Evolution** | 4/5 🟡 | - | | Guide has versioning and tracks changes. The v1.0/beta ve... |
35+
| **Completeness & Depth** | 4/5 🟡 | - | | Good depth on Graph-specific topics: delta queries with f... |
36+
| **Internal Consistency** | 5/5 🟢 | - | | Internally consistent with Graph API conventions. Termino... |
37+
| **Accessibility & Tone** | 4/5 🟡 | - | | Written for developers familiar with Microsoft Graph. Goo... |
38+
39+
---
40+
41+
### Findings
42+
43+
#### 🟡 Medium (1)
44+
45+
**Many Graph-specific rules require manual/LLM review rather than linting** [Enforceability & Tooling]
46+
-
47+
48+
#### 🟢 Low (3)
49+
50+
**Some inherited MS REST topics could be cross-referenced more explicitly** [Content Coverage]
51+
-
52+
53+
**Some rules have brief descriptions; more detail would help** [Rule Quality & Clarity]
54+
-
55+
56+
**Beta to v1.0 migration guidance could be expanded** [Guide Versioning & Evolution]
57+
-
58+
59+
---
60+
61+
### Next Steps
62+
63+
**Recommended:**
64+
65+
- [ ] Develop Graph-specific Spectral rules for OData patterns [Enforceability & Tooling]
66+
- [ ] Add explicit cross-references to base MS REST guide [Content Coverage]
67+
- [ ] Expand rule descriptions with implementation context [Rule Quality & Clarity]
68+
- [ ] Add beta-to-v1.0 API promotion migration guide [Guide Versioning & Evolution]
69+
70+
---
71+
72+
*Generated by structured-evaluation*

‎profiles/microsoft-graph/microsoft-graph.evaluation.txt‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
╔══════════════════════════════════════════════════════════════════════════════╗
2+
║ MICROSOFT GRAPH API GUIDELINES ║
3+
╠══════════════════════════════════════════════════════════════════════════════╣
4+
║ ✅ PASS ✅ ║
5+
╠══════════════════════════════════════════════════════════════════════════════╣
6+
║ CATEGORY ST SCORE DETAIL ║
7+
╟──────────────────────────────────────────────────────────────────────────────╢
8+
║ Content Coverage 🟡 4/5 Covers essential domains with Graph... ║
9+
║ Structure & Navigation 🟢 5/5 Excellent structure: TOC, GRAPH-XXX... ║
10+
║ Rule Quality & Clarity 🟡 4/5 Rules well-structured with IDs, tit... ║
11+
║ Examples & Code Samples 🟢 5/5 Excellent examples for Graph-specif... ║
12+
║ Enforceability & Tooling 🟡 3/5 Rules distinguish between lintable ... ║
13+
║ Guide Versioning & Evol... 🟡 4/5 Guide has versioning and tracks cha... ║
14+
║ Completeness & Depth 🟡 4/5 Good depth on Graph-specific topics... ║
15+
║ Internal Consistency 🟢 5/5 Internally consistent with Graph AP... ║
16+
║ Accessibility & Tone 🟡 4/5 Written for developers familiar wit... ║
17+
╠══════════════════════════════════════════════════════════════════════════════╣
18+
║ Categories: 8 pass, 1 partial, 0 fail ║
19+
║ Findings: 0 critical, 0 high, 1 medium, 3 low ║
20+
╠══════════════════════════════════════════════════════════════════════════════╣
21+
║ FINDINGS ║
22+
╟──────────────────────────────────────────────────────────────────────────────╢
23+
║ 🟡 [Enforceability & Tooling] Many Graph-specific rules require manual/LLM re...║
24+
╚══════════════════════════════════════════════════════════════════════════════╝

0 commit comments

Comments
 (0)