[DMS-877] Design Profiles Feature

docs/Profiles/examples/README.md

@@ -0,0 +1,152 @@
+# Example API Profiles
+
+This directory contains example API Profile XML documents that demonstrate common use cases for the Ed-Fi Data Management Service (DMS).
+
+## Available Profiles
+
+### 1. student-read-only.xml
+
+**Purpose**: Provides read-only access to basic student demographics  
+**Use Case**: External reporting systems that need basic student information  
+**Includes**: StudentUniqueId, names, birth date, school reference  
+**Excludes**: All collections, write access  
+
+### 2. student-write-limited.xml
+
+**Purpose**: Allows limited write access for demographic updates  
+**Use Case**: Student information system integration for basic data updates  
+**Includes**: Demographics, addresses, electronic mails  
+**Excludes**: Assessment data, program associations, identification codes  
+
+### 3. assessment-limited.xml
+
+**Purpose**: Restricts assessment data access to core fields only  
+**Use Case**: Assessment vendor with need-to-know access  
+**Includes**: Basic assessment results, student reference  
+**Excludes**: Accommodations, detailed objectives, performance levels  
+
+### 4. school-minimal.xml
+
+**Purpose**: Public-facing school directory information  
+**Use Case**: School finder applications, public directories  
+**Includes**: School ID, name, type, operational status, LEA reference  
+**Excludes**: Internal administrative data, staff assignments  
+
+### 5. descriptor-full-access.xml
+
+**Purpose**: Full access to descriptor resources  
+**Use Case**: Administrative users managing system descriptors  
+**Includes**: All descriptor fields (read and write)  
+**Excludes**: None  
+
+### 6. school-filtered-addresses.xml
+
+**Purpose**: School information with filtered address collections  
+**Use Case**: Public-facing directory showing only physical and mailing addresses  
+**Includes**: Basic school info, filtered addresses (Physical and Mailing only)  
+**Excludes**: Other address types (Temporary, Confidential, etc.)  
+**Demonstrates**: Collection item filtering using Filter elements  
+
+## Testing Profiles
+
+Each profile can be tested using the provided test scripts and data:
+
+```bash
+# Import a profile
+curl -X POST \
+  https://dms-api/v2/profiles/import \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -F "[email protected]"
+
+# Test the profile
+curl -X GET \
+  https://dms-api/data/v3/ed-fi/students/{id} \
+  -H "Accept: application/json;profile=student-read-only" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+## Customizing Profiles
+
+To create your own profile:
+
+1. Copy one of the example files
+2. Rename the profile in the `name` attribute
+3. Modify the `Resource` name if targeting a different resource
+4. Adjust `memberSelection` strategy (IncludeOnly, ExcludeOnly, etc.)
+5. Add or remove `Property`, `Collection`, and `Reference` elements
+6. Test in non-production environment
+7. Import to production when validated
+
+## Profile Naming Guidelines
+
+- Use descriptive names that indicate purpose
+- Include resource name if profile is resource-specific
+- Add version suffix for breaking changes (e.g., `-v2`)
+- Use kebab-case or PascalCase consistently
+
+Examples:
+
+- ✅ `Student-ReadOnly-Demographics`
+- ✅ `Assessment-Vendor-Limited-v2`
+- ✅ `School-Public-Directory`
+- ❌ `profile1`
+- ❌ `temp`
+
+## Validation
+
+Before importing to production:
+
+1. **XML Validation**: Ensure XML is well-formed
+
+   ```bash
+   xmllint --noout student-read-only.xml
+   ```
+
+2. **Schema Validation**: Verify against profile schema
+
+   ```bash
+   xmllint --schema profile-schema.xsd student-read-only.xml
+   ```
+
+3. **Functional Testing**: Test actual API behavior
+   - Import to test environment
+   - Execute read/write operations
+   - Verify filtering works as expected
+   - Test error cases
+
+4. **Performance Testing**: Measure impact
+   - Compare response times with/without profile
+   - Check cache effectiveness
+   - Monitor resource usage
+
+## Documentation
+
+For complete documentation on API Profiles, see:
+
+- [API Profiles Design](../API-PROFILES-DESIGN.md) - Comprehensive architecture and design
+- [API Profiles Quick Start](../API-PROFILES-QUICKSTART.md) - Getting started guide
+- [Ed-Fi API Profiles Specification](https://edfi.atlassian.net/wiki/spaces/EDFICERT/pages/20874540/Profiles) - Official specification
+
+## Contributing
+
+To contribute new example profiles:
+
+1. Create profile XML following the guidelines above
+2. Add comprehensive comments explaining purpose and use case
+3. Provide test scenarios and expected behavior
+4. Update this README with profile description
+5. Submit pull request with changes
+
+## Support
+
+For questions or issues with these profiles:
+
+- Review the Quick Start guide
+- Check the troubleshooting section in the main documentation
+- Post in Ed-Fi community forums
+- Contact Ed-Fi support
+
+---
+
+**Last Updated**: 2025-12-09  
+**Compatible With**: DMS 1.0+

docs/Profiles/examples/assessment-limited.xml

@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Profile: Assessment-Limited
+  Purpose: Restricts assessment data access to core fields only
+  Use Case: Assessment vendor integration with need-to-know access restrictions
+  Version: 1.0
+  Created: 2025-12-09
+
+  This profile provides read access to basic assessment results while excluding:
+  - Student accommodations (privacy concern)
+  - Detailed objective assessments (proprietary)
+  - Performance level descriptors (detailed scoring)
+  - Student assessment extensions (custom fields)
+
+  Write access is completely restricted for this profile.
+-->
+<Profile name="Assessment-Limited">
+  <Resource name="StudentAssessment">
+    <ReadContentType memberSelection="ExcludeOnly">
+      <!-- Exclude Sensitive/Detailed Information -->
+      <Collection name="StudentAssessmentAccommodations" memberSelection="ExcludeAll" />
+      <Collection name="StudentAssessmentStudentObjectiveAssessments" memberSelection="ExcludeAll" />
+      <Collection name="StudentAssessmentPerformanceLevels" memberSelection="ExcludeAll" />
+      <Collection name="StudentAssessmentScoreResults" memberSelection="IncludeOnly">
+        <!-- Allow basic scores, exclude detailed breakdowns -->
+        <Property name="Result" />
+        <Property name="ResultDatatypeTypeDescriptor" />
+        <!-- Exclude AssessmentReportingMethodDescriptor to hide scoring methodology -->
+      </Collection>
+    </ReadContentType>
+    <!-- No WriteContentType = Read-only access -->
+  </Resource>
+
+  <Resource name="Assessment">
+    <ReadContentType memberSelection="IncludeOnly">
+      <!-- Basic Assessment Metadata Only -->
+      <Property name="AssessmentIdentifier" />
+      <Property name="AssessmentTitle" />
+      <Property name="AssessmentVersion" />
+      <Property name="MaxRawScore" />
+      <Reference name="EducationOrganizationReference">
+        <Property name="EducationOrganizationId" />
+      </Reference>
+    </ReadContentType>
+  </Resource>
+</Profile>

docs/Profiles/examples/descriptor-full-access.xml

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Profile: Descriptor-Full-Access
+  Purpose: Complete access to descriptor resources for system administration
+  Use Case: System administrators managing Ed-Fi descriptors and enumerations
+  Version: 1.0
+  Created: 2025-12-09
+
+  This profile grants unrestricted read and write access to all descriptor types.
+  Descriptors are reference data (enumerations) used throughout the Ed-Fi data model.
+
+  Use this profile for:
+  - System administrators
+  - Descriptor management tools
+  - Data setup and configuration
+
+  Security Note: Limit assignment of this profile to trusted, authenticated administrators only.
+-->
+<Profile name="Descriptor-Full-Access">
+  <!-- 
+    Note: This profile applies to all descriptor types:
+    - AcademicSubjectDescriptor
+    - GradeLevelDescriptor
+    - StateAbbreviationDescriptor
+    - etc. (100+ descriptor types in Ed-Fi)
+  -->
+  <Resource name="Descriptor">
+    <ReadContentType memberSelection="IncludeAll">
+      <!-- Include all fields for reading descriptors -->
+    </ReadContentType>
+
+    <WriteContentType memberSelection="IncludeAll">
+      <!-- Include all fields for creating/updating descriptors -->
+    </WriteContentType>
+  </Resource>
+
+  <!-- Example: Specific descriptor type (optional, more granular) -->
+  <Resource name="GradeLevelDescriptor">
+    <ReadContentType memberSelection="IncludeAll" />
+    <WriteContentType memberSelection="IncludeAll" />
+  </Resource>
+
+  <Resource name="AcademicSubjectDescriptor">
+    <ReadContentType memberSelection="IncludeAll" />
+    <WriteContentType memberSelection="IncludeAll" />
+  </Resource>
+</Profile>