Merge branch 'main' of https://github.com/microsoftgraph/microsoft-graph-docs

Author: OWinfreyATL

.gdn/.gdnbaselines

@@ -16,16 +16,41 @@
     "b3d46ea406a66acd0fa8b1130ec9be5b501ad4a933d98ce70193c68771b6e7be": {
       "signature": "b3d46ea406a66acd0fa8b1130ec9be5b501ad4a933d98ce70193c68771b6e7be",
       "alternativeSignatures": [
-        "79e125fb7927450b0ebb02d6b3ddb03d7a6a971e21dfdc1c246ba8fd39f0969e"
+        "79e125fb7927450b0ebb02d6b3ddb03d7a6a971e21dfdc1c246ba8fd39f0969e",
+        "11e53a6e53ef601debd4d1a4dc1ca3d451cd0c96df1892e7f5685b8c6d01769b"
       ],
-      "target": "update-permissions-reference.ps1",
+      "target": "scripts/update-permissions-reference.ps1",
       "line": 170,
       "memberOf": [
         "default"
       ],
       "tool": "psscriptanalyzer",
       "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
       "createdDate": "2024-08-26 12:06:54Z"
+    },
+    "11e53a6e53ef601debd4d1a4dc1ca3d451cd0c96df1892e7f5685b8c6d01769b": {
+      "signature": "11e53a6e53ef601debd4d1a4dc1ca3d451cd0c96df1892e7f5685b8c6d01769b",
+      "alternativeSignatures": [],
+      "target": "scripts/update-permissions-reference.ps1",
+      "line": 177,
+      "memberOf": [
+        "default"
+      ],
+      "tool": "psscriptanalyzer",
+      "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
+      "createdDate": "2026-02-24 12:06:54Z"
+    },
+    "261f3837d9978ecb7637c62a4ced8a0eb843e19a07557738ce232dc24410ac96": {
+      "signature": "261f3837d9978ecb7637c62a4ced8a0eb843e19a07557738ce232dc24410ac96",
+      "alternativeSignatures": [],
+      "target": "update-permissions-reference-fic.ps1",
+      "line": 179,
+      "memberOf": [
+        "default"
+      ],
+      "tool": "psscriptanalyzer",
+      "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
+      "createdDate": "2026-02-24 12:06:54Z"
     }
   }
 }

.gdn/.gdnsuppress

@@ -16,16 +16,41 @@
     "b3d46ea406a66acd0fa8b1130ec9be5b501ad4a933d98ce70193c68771b6e7be": {
       "signature": "b3d46ea406a66acd0fa8b1130ec9be5b501ad4a933d98ce70193c68771b6e7be",
       "alternativeSignatures": [
-        "79e125fb7927450b0ebb02d6b3ddb03d7a6a971e21dfdc1c246ba8fd39f0969e"
+        "79e125fb7927450b0ebb02d6b3ddb03d7a6a971e21dfdc1c246ba8fd39f0969e",
+        "11e53a6e53ef601debd4d1a4dc1ca3d451cd0c96df1892e7f5685b8c6d01769b"
       ],
-      "target": "update-permissions-reference.ps1",
+      "target": "scripts/update-permissions-reference.ps1",
       "line": 170,
       "memberOf": [
         "default"
       ],
       "tool": "psscriptanalyzer",
       "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
       "createdDate": "2024-08-26 12:06:54Z"
+    },
+    "11e53a6e53ef601debd4d1a4dc1ca3d451cd0c96df1892e7f5685b8c6d01769b": {
+      "signature": "11e53a6e53ef601debd4d1a4dc1ca3d451cd0c96df1892e7f5685b8c6d01769b",
+      "alternativeSignatures": [],
+      "target": "scripts/update-permissions-reference.ps1",
+      "line": 177,
+      "memberOf": [
+        "default"
+      ],
+      "tool": "psscriptanalyzer",
+      "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
+      "createdDate": "2026-02-24 12:06:54Z"
+    },
+    "261f3837d9978ecb7637c62a4ced8a0eb843e19a07557738ce232dc24410ac96": {
+      "signature": "261f3837d9978ecb7637c62a4ced8a0eb843e19a07557738ce232dc24410ac96",
+      "alternativeSignatures": [],
+      "target": "update-permissions-reference-fic.ps1",
+      "line": 179,
+      "memberOf": [
+        "default"
+      ],
+      "tool": "psscriptanalyzer",
+      "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
+      "createdDate": "2026-02-24 12:06:54Z"
     }
   }
 }

.github/prompts/author-api-docs.prompt.md

@@ -37,7 +37,7 @@ Ask the reviewer which documentation changes need to be reviewed:
 While not required, providing these files significantly improves review quality and completeness:
 
 **Optional Context Files (provide if available):**
-- **Summary of API changes in documentation-plan.md:** A description of what documentation changes were expected based on the schema changes (identifies files changed, methods documented, resources added/updated, namespace information)
+- **Documentation Plan in documentation-plan.md:** A description of what documentation changes were expected based on the schema changes (identifies files changed, methods documented, resources added/updated, namespace information)
 - **API.md file:** The API specification file describing capabilities in detail
 
 **Why these files help:**
@@ -49,6 +49,62 @@ While not required, providing these files significantly improves review quality
 
 ---
 
+## Common Process: Validation
+
+As part of the review process, validate that automated validation scripts pass. These scripts ensure compliance with required standards and prevent common errors.
+
+### Validate changelog JSON files
+
+After reviewing changelog changes, run the changelog validation script:
+
+```powershell
+.\scripts\validate-changelog-json.ps1
+```
+
+**Purpose:**
+- Validates all changelog files in the `changelog/` folder against the schema
+- Checks schema compliance, required properties, and formatting
+- Ensures proper JSON structure and required metadata
+
+**What it validates:**
+- Complete record structure (ChangeList array + Id, Cloud, Version, CreatedDateTime, WorkloadArea, SubArea)
+- GUID consistency across ChangeList items and record-level Id
+- Cloud value is "prd" (or "Prod" - case variations allowed)
+- Version value is "v1.0" or "beta"
+- CreatedDateTime in ISO 8601/RFC 3339 format with fractional seconds and Z suffix
+- WorkloadArea and SubArea match CDK taxonomy
+
+**Must pass before:** Approving PR with changelog updates
+
+### Validate temp-docstubs cleanup (if applicable)
+
+If reviewing changes that involved the temp-docstubs folder, verify cleanup:
+
+```powershell
+.\scripts\validate-temp-docstubs.ps1
+```
+
+**Purpose:**
+- Verifies that only `temp-docstubs-instructions.md` remains in temp-docstubs folder
+- Prevents accidental commit of temporary input files (autogenerated doc stubs, API.md files, changelog files)
+
+**Must pass before:** Approving PR that touched temp-docstubs folder
+
+### When validation fails
+
+**If validation scripts report errors:**
+1. Review error messages to identify specific issues
+2. Flag the issues in your review report under "Critical Issues (Must Fix)"
+3. Provide guidance on correcting the problems
+4. Request author to re-run validation after fixes
+5. Do not approve until all validation checks pass
+
+**Common validation failures:**
+- Changelog: Missing required properties, incorrect date format, malformed JSON
+- temp-docstubs: Temporary files not removed before commit
+
+---
+
 ## Review Guidelines
 
 The review process applies guidelines from three authoritative sources. You should check all sets of guidelines without duplication:
@@ -145,22 +201,24 @@ For files in `api-reference/v1.0/resources/` and `api-reference/beta/resources/`
 
 ### Changelog Files Review
 
-For files in `changelog/`, verify structure matches [templates/changelog-patterns.md](templates/changelog-patterns.md).
+For files in `changelog/`, verify structure matches [templates/changelog-patterns.md](templates/changelog-patterns.md) and run validation (see [Common Process: Validation](#common-process-validation)).
 
 **Required Elements:**
 - [ ] Complete changelog record structure (ChangeList array + Id, Cloud, Version, CreatedDateTime, WorkloadArea, SubArea)
 - [ ] Same GUID in all ChangeList items and record-level Id
-- [ ] Cloud value is "prd"
+- [ ] Cloud value is "prd" (or "Prod")
 - [ ] Version value is "v1.0" or "beta"
 - [ ] CreatedDateTime in ISO 8601/RFC 3339 format with fractional seconds and Z suffix (e.g., "2025-11-17T17:38:10.4694969Z")
 - [ ] Description links use full URLs with en-us locale
 - [ ] WorkloadArea and SubArea match CDK taxonomy (https://aka.ms/msgraphcdk)
+- [ ] Validation script passes (see [Common Process: Validation](#common-process-validation))
 
 **Common Issues:**
 - [ ] Multiple unrelated API elements in single ChangeList item
 - [ ] Missing or vague descriptions
 - [ ] Malformed links or missing en-us locale
 - [ ] Incomplete record structure (missing metadata)
+- [ ] Validation script failures
 
 ### Version-Specific Validation
 
@@ -205,7 +263,7 @@ Verify compliance with formatting rules detailed in [author-api-docs.prompt.md -
 
 ## Optional Context-Enhanced Review
 
-If the reviewer provided context files (Summary of API changes in documentation-plan.md or API.md):
+If the reviewer provided context files (Documentation Plan in documentation-plan.md or API.md):
 
 ### Validate Against Summary of API Changes
 
@@ -252,7 +310,16 @@ Group files by type:
 
 For each file, apply the appropriate review checklist from above.
 
-### Step 4: Report Findings
+### Step 4: Run Validation Scripts
+
+Run automated validation scripts to ensure compliance (see [Common Process: Validation](#common-process-validation)):
+
+1. **If changelog files were modified:** Run `.\scripts\validate-changelog-json.ps1`
+2. **If temp-docstubs folder is present in the branch:** Run `.\scripts\validate-temp-docstubs.ps1`
+
+Include validation results in your review report. Flag any validation failures as critical issues.
+
+### Step 5: Report Findings
 
 Provide a structured review report:
 
@@ -275,7 +342,7 @@ For each file with issues, list:
 - Suggested fix (when applicable)
 - Line numbers or section references
 
-### Step 5: Optional - Suggest Fixes
+### Step 6: Optional - Suggest Fixes
 
 If requested, provide specific edits to fix identified issues.
 
@@ -304,6 +371,10 @@ If requested, provide specific edits to fix identified issues.
 **Files with Issues:** 3
 **Files Approved:** 5
 
+**Validation Results:**
+- ✓ Changelog validation passed (.\scripts\validate-changelog-json.ps1)
+- ✓ temp-docstubs validation passed (.\scripts\validate-temp-docstubs.ps1)
+
 ---
 
 ## Critical Issues (Must Fix)
@@ -345,6 +416,8 @@ If requested, provide specific edits to fix identified issues.
   - Current: "Added property"
   - Suggestion: "Added the **newProperty** property to enable..."
 
+### API overview updates
+- If an API Overview topic covers the same APIs, consider updating it to reflect new capabilities and changes for better discoverability and context for users.
 ---
 
 ## Files Approved
@@ -362,11 +435,13 @@ If requested, provide specific edits to fix identified issues.
 
 1. **Start with file classification** - Understanding file types helps apply the right rules
 2. **Check metadata first** - Validate namespace, doc_type, and version before content review
-3. **Use find/search** - Look for TODO placeholders across all files
-4. **Validate links** - Ensure all referenced resources and types exist and are correctly linked
-5. **Check consistency** - Resource names, namespaces, and terminology should be consistent across all files
-6. **Compare with context** - If Summary of API changes (documentation-plan.md file) or API.md provided, validate against them first
-7. **Flag autogeneration issues** - If doc stubs appear to have over-generated content, mention this
+3. **Run validation scripts early** - Check changelog and temp-docstubs validation before detailed review
+4. **Use find/search** - Look for TODO placeholders across all files
+5. **Validate links** - Ensure all referenced resources and types exist and are correctly linked
+6. **Check consistency** - Resource names, namespaces, and terminology should be consistent across all files
+7. **Compare with context** - If Summary of API changes (documentation-plan.md file) or API.md provided, validate against them first
+8. **Flag autogeneration issues** - If doc stubs appear to have over-generated content, mention this
+9. **Include validation results** - Always report validation script results in your review summary
 
 ---
 

.github/prompts/review-api-docs.prompt.md

@@ -2,6 +2,7 @@
 > Required for API changes:
 > - [] Link to API.md file: *ADD LINK HERE*
 > - [] Link to **PR** for public-facing schema changes (schema-Prod-beta/v1.0.csdl):  *ADD LINK HERE*
+> - [] OPTIONAL: Attach the documentation plan generated for AI-assisted docs authoring and validation to help speed up content review.
 
 ---
 Add other supporting information, such as a description of the PR changes:

.github/pull_request_template.md

@@ -10,12 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Validate JSON
-        uses: docker://orrosenblatt/validate-json-action:latest
-        env:
-          INPUT_SCHEMA: /changelog/Changelog.Schema.json
-          INPUT_JSONS: /changelog/Manual.NonWorkloadChanges.json,/changelog/Microsoft.AAD.Reporting.json,/changelog/Microsoft.Analytics.json,/changelog/Microsoft.BitLocker.json,/changelog/Microsoft.CloudManagedDesktop.json,/changelog/Microsoft.Compliance.Ediscovery.json,/changelog/Microsoft.DirectoryServices.json,/changelog/Microsoft.EducationAssignment.json,/changelog/Microsoft.Excel.json,/changelog/Microsoft.Exchange.json,/changelog/Microsoft.FileServices.json,/changelog/Microsoft.HybridAuthentication.json,/changelog/Microsoft.IdentityGovernance.AccessReviews.json,/changelog/Microsoft.IdentityProtectionServices.json,/changelog/Microsoft.Intune.json,/changelog/Microsoft.MicrosoftSearch.json,/changelog/Microsoft.NAV.json,/changelog/Microsoft.O365Reporting.json,/changelog/Microsoft.Office.Tasks.json,/changelog/Microsoft.OneNote.json,/changelog/Microsoft.PrintService.json,/changelog/Microsoft.Search.json,/changelog/Microsoft.SharePoint.json,/changelog/Microsoft.Skype.Calling.json,/changelog/Microsoft.SubscriptionServices.json,/changelog/Microsoft.Teams.Core.json,/changelog/Microsoft.Teams.GraphSvc.json,/changelog/Microsoft.ThreatAssessment.json,/changelog/Microsoft.Todo.json,/changelog/Microsoft.People.json
-      - name: Validate Schema with Script
+      - name: Validate Changelog JSONs with Schema
         run: |
-          ./validate-changelog-json.ps1
+          ./scripts/validate-changelog-json.ps1
         shell: pwsh

.github/workflows/changelog-validation.yml

@@ -0,0 +1,90 @@
+name: Update permissions reference file (FIC)
+
+on:
+  schedule:
+    - cron: 0 6 * * 1  # Runs every Monday at 6 AM UTC
+  workflow_dispatch:  # Allows manual triggering of the workflow
+    
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write  # Required for federated identity credentials
+  
+jobs:
+  update-permissions-reference:
+    name: Update permissions reference (FIC)
+    runs-on: windows-latest
+    
+    steps:
+    - name: Set up Git to handle long paths
+      run: git config --system core.longpaths true
+
+    - name: Checkout microsoft-graph-docs
+      uses: actions/checkout@v4.1.3
+      with:
+        path: docs
+
+    - name: Azure Login using Federated Identity
+      uses: azure/login@v2
+      with:
+        client-id: ${{ secrets.GRAPHPERMISSIONSREFERENCE_AZURE_CLIENT_ID }}
+        tenant-id: ${{ secrets.GRAPHPERMISSIONSREFERENCE_AZURE_TENANT_ID }}
+        allow-no-subscriptions: true
+
+    - name: Run PowerShell script to update permissions
+      shell: pwsh
+      run: | 
+        $ClientId = "${{ secrets.GRAPHPERMISSIONSREFERENCE_AZURE_CLIENT_ID }}"
+        $TenantId = "${{ secrets.GRAPHPERMISSIONSREFERENCE_AZURE_TENANT_ID }}"
+        ./docs/update-permissions-reference-fic.ps1 -ClientId $ClientId -TenantId $TenantId
+        
+    - name: Get token
+      id: get_token
+      uses: microsoftgraph/get-app-token@v1.0.4
+      with: 
+        application-id: ${{ secrets.APPLICATION_ID }}
+        application-private-key: ${{ secrets.APPLICATION_PRIVATE_KEY }}
+        
+    - name: Commit updates from service principal
+      working-directory: ./docs
+      shell: pwsh
+      env:
+        GH_TOKEN: ${{ steps.get_token.outputs.app-token }}
+      run: |
+        $status = git status --porcelain
+        if ($status -eq $null) {
+          Write-Host "No changes to commit." -ForegroundColor Green
+        }
+        else {          
+          git config user.email "GraphTooling@service.microsoft.com"
+          git config user.name "Microsoft Graph DevX Tooling"
+          git add .
+          git commit -m "Update permissions reference"
+        } 
+    
+    - name: Run PowerShell script to correct errors in permissions descriptions
+      shell: pwsh
+      run: | 
+        ./docs/correct-permissions-reference-errors.ps1
+    
+    - name: Commit errors correction and open a pull request
+      working-directory: ./docs
+      shell: pwsh
+      env:
+       GH_TOKEN: ${{ steps.get_token.outputs.app-token }}
+      run: |
+        $status = git status --porcelain
+        if ($status -eq $null) {
+          Write-Host "No changes to commit." -ForegroundColor Green
+        } else { 
+          $dateToday = Get-Date -Format 'yyyy-MM-dd'
+          $branchName = "permissions-reference/$dateToday" 
+          $prTitle = "${dateToday}: Automated permissions reference update (FIC)"
+          
+          git add .
+          git commit -m "Correct errors in permissions reference"
+          git checkout -b $branchName
+          git push --set-upstream origin $branchName -f
+          
+          gh pr create --base main --title $prTitle --body "Scheduled permissions reference update using Federated Identity Credentials" --reviewer "FaithOmbongi,msewaweru" --label "ready for content review"
+        }

.github/workflows/permissions-reference-gen-fic.yml

@@ -29,7 +29,7 @@ jobs:
         $ClientId = "${{ secrets.GRAPHPERMISSIONSREFERENCE_CLIENT_ID }}"
         $TenantId = "${{ secrets.GRAPHPERMISSIONSREFERENCE_TENANT_ID }}"
         $ClientSecret = "${{ secrets.GRAPHPERMISSIONSREFERENCE_CLIENT_SECRET }}"
-        ./docs/update-permissions-reference.ps1 -ClientId $ClientId -TenantId $TenantId -ClientSecret $ClientSecret
+        ./docs/scripts/update-permissions-reference.ps1 -ClientId $ClientId -TenantId $TenantId -ClientSecret $ClientSecret
         
     - name: Get token
       id: get_token
@@ -58,7 +58,7 @@ jobs:
     - name: Run PowerShell script to correct errors in permissions descriptions
       shell: pwsh
       run: | 
-        ./docs/correct-permissions-reference-errors.ps1
+        ./docs/scripts/correct-permissions-reference-errors.ps1
     
     - name: Commit errors correction and open a pull request
       working-directory: ./docs