001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.revetsec.scim; 018 019import com.google.errorprone.annotations.CheckReturnValue; 020import com.revetsec.internal.json.AsciiCase; 021import org.jspecify.annotations.NonNull; 022import org.jspecify.annotations.Nullable; 023import javax.annotation.concurrent.Immutable; 024import javax.annotation.concurrent.NotThreadSafe; 025import java.util.List; 026import java.util.Objects; 027import java.util.Optional; 028 029/** 030 * Immutable SCIM schema registration. Schema identifiers are bounded absolute URI strings; 031 * they are never fetched. Application schemas cannot override common resource attributes. 032 * 033 * @since 1.0.0 034 */ 035@Immutable 036@CheckReturnValue 037public final class ScimSchema { 038 private final @NonNull String id; 039 private final @NonNull String name; 040 private final @Nullable String description; 041 private final @NonNull List<@NonNull ScimAttributeDefinition> attributes; 042 private final boolean discovery; 043 044 private ScimSchema(@NonNull Builder builder, boolean discovery) { 045 if (builder.name == null) 046 throw new IllegalStateException("A SCIM schema requires a name."); 047 id = builder.id; 048 name = builder.name; 049 description = builder.description; 050 attributes = builder.attributes; 051 this.discovery = discovery; 052 ScimSchemas.requireDistinctAttributes(attributes); 053 int count = 0; 054 for (ScimAttributeDefinition definition : attributes) { 055 count += definition.definitionCount(); 056 if (!discovery) { 057 if (ScimSchemas.isCommonName(definition.getName()) || AsciiCase.fold(definition.getName()).equals("$ref")) 058 throw new IllegalArgumentException("Application schemas cannot override common SCIM attributes."); 059 for (ScimAttributeDefinition child : definition.getSubAttributes()) 060 if (child.getType() == ScimAttributeType.COMPLEX) 061 throw new IllegalArgumentException("Nested complex application SCIM attributes are unsupported."); 062 } 063 } 064 ScimSchemas.requireDefinitionCount(count); 065 } 066 067 /** 068 * Starts an application schema with its required absolute URI identifier. 069 * @param id the required schema identifier 070 * @return a new builder 071 * @since 1.0.0 072 */ 073 public static @NonNull Builder withId(@NonNull String id) { return new Builder(ScimSchemas.requireSchemaId(id)); } 074 075 /** 076 * Returns the schema URI identifier. 077 * @return the schema URI identifier 078 * @since 1.0.0 079 */ 080 public @NonNull String getId() { return id; } 081 082 /** 083 * Returns the human-readable schema name. 084 * @return the human-readable schema name 085 * @since 1.0.0 086 */ 087 public @NonNull String getName() { return name; } 088 089 /** 090 * Returns the optional schema description. 091 * @return the optional schema description 092 * @since 1.0.0 093 */ 094 public @NonNull Optional<@NonNull String> getDescription() { return Optional.ofNullable(description); } 095 096 /** 097 * Returns the immutable schema-specific definitions. Common resource definitions are inherited. 098 * @return the immutable schema-specific definitions 099 * @since 1.0.0 100 */ 101 public @NonNull List<@NonNull ScimAttributeDefinition> getAttributes() { return attributes; } 102 103 /** 104 * Returns the shared standard User schema, with reviewed RFC corrections. 105 * @return the standard schema 106 * @since 1.0.0 107 */ 108 public static @NonNull ScimSchema userInstance() { return ScimSchemas.user(); } 109 110 /** 111 * Returns the shared standard Group schema, with reviewed RFC corrections. 112 * @return the standard schema 113 * @since 1.0.0 114 */ 115 public static @NonNull ScimSchema groupInstance() { return ScimSchemas.group(); } 116 117 /** 118 * Returns the shared standard Enterprise User extension schema, with reviewed RFC corrections. 119 * @return the standard schema 120 * @since 1.0.0 121 */ 122 public static @NonNull ScimSchema enterpriseUserInstance() { return ScimSchemas.enterpriseUser(); } 123 124 /** 125 * Returns the shared standard ServiceProviderConfig discovery schema, with reviewed RFC corrections. 126 * @return the standard schema 127 * @since 1.0.0 128 */ 129 public static @NonNull ScimSchema serviceProviderConfigInstance() { return ScimSchemas.serviceProviderConfig(); } 130 131 /** 132 * Returns the shared standard ResourceType discovery schema, with reviewed RFC corrections. 133 * @return the standard schema 134 * @since 1.0.0 135 */ 136 public static @NonNull ScimSchema resourceTypeInstance() { return ScimSchemas.resourceType(); } 137 138 /** 139 * Returns the shared standard Schema discovery schema, with reviewed RFC corrections. 140 * @return the standard schema 141 * @since 1.0.0 142 */ 143 public static @NonNull ScimSchema schemaInstance() { return ScimSchemas.schema(); } 144 145 /** 146 * Compares semantic schema registrations, folding the schema identifier. 147 * @param other the comparison value 148 * @return whether registrations have equal characteristics 149 * @since 1.0.0 150 */ 151 @Override public boolean equals(@Nullable Object other) { 152 return this == other || (other instanceof ScimSchema schema && discovery == schema.discovery 153 && AsciiCase.fold(id).equals(AsciiCase.fold(schema.id)) && name.equals(schema.name) 154 && Objects.equals(description, schema.description) && attributes.equals(schema.attributes)); 155 } 156 157 /** 158 * Returns the semantic registration hash. 159 * @return the semantic hash 160 * @since 1.0.0 161 */ 162 @Override public int hashCode() { return Objects.hash(AsciiCase.fold(id), name, description, attributes, discovery); } 163 164 /** 165 * Returns a fixed redacted description. 166 * @return a fixed redacted description 167 * @since 1.0.0 168 */ 169 @Override public @NonNull String toString() { return "ScimSchema{<redacted>}"; } 170 171 boolean isDiscovery() { return discovery; } 172 static @NonNull ScimSchema fromDiscovery(@NonNull Builder builder) { return new ScimSchema(builder, true); } 173 174 /** 175 * Mutable, non-thread-safe schema configuration. Null restores the stated default. 176 * @since 1.0.0 177 */ 178 @NotThreadSafe 179 @CheckReturnValue 180 public static final class Builder { 181 private final @NonNull String id; 182 private @Nullable String name; 183 private @Nullable String description; 184 private @NonNull List<@NonNull ScimAttributeDefinition> attributes = List.of(); 185 private Builder(@NonNull String id) { this.id = id; } 186 187 /** 188 * Sets the required schema name; null restores unset. 189 * @param value the name, or null to restore unset 190 * @return this builder 191 * @since 1.0.0 192 */ 193 public @NonNull Builder name(@Nullable String value) { 194 name = value == null ? null : ScimSchemas.requireName(value); return this; 195 } 196 197 /** 198 * Sets the optional description; null restores absent. 199 * @param value the description, or null to restore absent 200 * @return this builder 201 * @since 1.0.0 202 */ 203 public @NonNull Builder description(@Nullable String value) { 204 description = value == null ? null : ScimSchemas.requireText(value, false); return this; 205 } 206 207 /** 208 * Replaces and snapshots the complete bounded definition list; null restores empty. 209 * @param value definitions, or null to restore empty 210 * @return this builder 211 * @since 1.0.0 212 */ 213 public @NonNull Builder attributes(@Nullable List<@NonNull ScimAttributeDefinition> value) { 214 attributes = value == null ? List.of() : ScimSchemas.attributes(value); return this; 215 } 216 217 /** 218 * Checks application-resource characteristics and creates an immutable schema. 219 * @return the schema 220 * @since 1.0.0 221 */ 222 public @NonNull ScimSchema build() { return new ScimSchema(this, false); } 223 } 224}