@microsoft/typespec-msgraph 0.0.1-Preview.1 → 0.0.1-Preview.11

package/lib/decorators.tsp

@@ -1,14 +1,43 @@
 using TypeSpec.Reflection;
 
 /**
- * TODO: Enable this once Model type is supported. https://github.com/microsoft/typespec/issues/1655
- * 
  * `@abstract` - mark a model type as abstract
  *
  * `@abstract` can only be applied to models.
-
+ */
 extern dec abstract(target: Model);
-*/
+
+/**
+ * `@action` - mark an operation as an action
+ *
+ * `@action` can only be applied to operations.
+ */
+extern dec action(target: Operation, name?: valueof string);
+
+/**
+ * `@additionalQueryParameters` - Appends a key=value pair to the query string of the mapped internal URL for all models defined within the namespace.
+ * 
+ * `@additionalQueryParameters` can only be applied to namespaces
+ */
+extern dec additionalQueryParameters(target: Namespace, name: valueof string, value: valueof string);
+
+/**
+ * `@agsAttribute` - Allows all AGS CSDL extensions that are not yet modelled explicitly in TypeSpec to be maintained
+ * 
+ * `@agsAttribute` - Applies to models.
+ */
+extern dec agsAttribute(
+  target: Model | ModelProperty | Enum | EnumMember | Operation | Interface,
+  name: valueof string,
+  value: valueof string
+);
+
+/**
+ * `@allowedValues` - mark model property with allowedValues.
+ * 
+ * `@allowedValues` - can only be applied to model properties.
+ */
+ extern dec allowedValues(target: ModelProperty, ...values: valueof unknown[]);
 
 /**
  * `@alternateKey` - mark a model property as an alternateKey
@@ -18,14 +47,11 @@ extern dec abstract(target: Model);
 extern dec alternateKey(target: ModelProperty);
 
 /**
- * TODO: Enable this once Model type is supported. https://github.com/microsoft/typespec/issues/1655
- *
  * `@complex` - mark a model as an entity type
  *
  * `@complex` can only be applied to models.
-
-extern dec complex(target: Model);
  */
+extern dec complex(target: Model);
 
 /**
  * `@computed` - mark a model property as a computed property
@@ -48,28 +74,32 @@ extern dec contains(target: ModelProperty);
  */
 extern dec count(target: Operation);
 
+/**
+ * `@deltaCollection` - mark a model as representing a delta paged collection.
+ *
+ * `@deltaCollection` can only be applied to models.
+ */
+extern dec deltaCollection(target: Model);
+
 /**
  * `@deprecatedDefinition` - Allow us create a reusable deprecation definition.
  * `@deprecatedDefinition` - Applies only to namespaces.
  */
 extern dec deprecatedDefinition(
   target: Namespace,
-  name: string,
-  category: string,
-  announcementDate: string,
-  removalDate: string,
-  description: string
+  name: valueof string,
+  category: valueof string,
+  announcementDate: valueof string,
+  removalDate: valueof string,
+  description: valueof string
 );
 
 /**
- * TODO: Enable this once Model type is supported. https://github.com/microsoft/typespec/issues/1655
- *
  * `@entity` - mark a model as an entity type
  *
  * `@entity` can only be applied to models.
-
-extern dec entity(target: Model);
  */
+extern dec entity(target: Model);
 
 /**
  * `@expand` - Applies to: get operations that return collections or individual instances of models that contain @contains or @references properties.
@@ -78,18 +108,71 @@ extern dec entity(target: Model);
  * `properties` - Property names in the model returned from the get that can be used in a $expand query parameter.
  * At least one property must be specified.
  */
-extern dec expand(target: Operation, property: string, ...otherProperties: string[]);
+extern dec expand(target: Operation, property: valueof string, ...otherProperties: valueof string[]);
+
+/**
+ * `@filter` - Applies to: get operations that return collections of @entity or @complex models.
+ * Indicates that the get operation supports OData $filter query parameter.
+ *
+ * `properties` - array of property names in the model returned
+ * from the get operation that can be used in $filter query parameter.
+ */
+extern dec filter(target: Operation, property: valueof string, ...properties: valueof string[]);
+
 
 /**
- * TODO: Enable this once Model type is supported. https://github.com/microsoft/typespec/issues/1655
+ * `@flags` - mark an enumeration type as a flag.
  *
+ * `@flags` can only be applied to enums.
+ */
+extern dec flags(target: Enum);
+
+/**
+ * `@function` - mark an operation as a function
+ *
+ * `@function` can only be applied to operations.
+ */
+extern dec function(target: Operation, name?: valueof string);
+
+/**
+ * `@graphRoute` - mark an interface or operation with an HTTP route.
+ * 
+ * `@graphRoute` - can only be applied to interfaces or operations.
+ */
+// TODO: Using @graphRoute on an operation currently does not work due to the following TypeSpec core issue
+// https://github.com/microsoft/typespec/issues/2106
+// Disabling all related features while we await the outcome.
+extern dec graphRoute(target: Interface /* | Operation */, path: valueof string);
+
+/**
  * `@hasStream` - indicates that an `@entity` model has a stream.
  *
- * `mediaTypes` - list of media types supported by the stream.
- * If not specified, the stream supports any media type.
- 
- extern dec hasStream(target: Model, ...mediaTypes: string[]);
+ * `mediaTypes` - list of media types supported by the stream. If not specified, the stream supports any media type.
+ */
+extern dec hasStream(target: Model, ...mediaTypes: valueof string[]);
+
+/**
+ * `@immutable` - mark a model property as immutable.
+ *
+ * `@immutable` can only be applied to model properties.
+ */
+extern dec immutable(target: ModelProperty);
+
+/**
+ * `@open` - mark a model type as open
+ *
+ * `@open` can only be applied to models.
  */
+extern dec open(target: Model);
+
+/**
+ * `@operationParameters` - A model with this decorator will not be generated in the CSDL
+ * and can't be reused by other models through inheritance,
+ * or any other way except through being a parameter for an action operation.
+ * The purpose of this model is only to define model parameters that would be too verbose.
+ * This decorator will be the equivalent of inlining the properties of the model into parameters of the operation.
+ */
+extern dec operationParameters(target: Model);
 
 /**
  * `@orderBy` - Applies to: get operations that return collections of @entity or @complex models.
@@ -98,19 +181,30 @@ extern dec expand(target: Operation, property: string, ...otherProperties: strin
  * `properties` - List of property names in the model returned from the get operation that can be used in a $orderBy query parameter.
  * At least one property must be specified.
  */
-extern dec orderBy(target: Operation, property: string, ...otherProperties: string[]);
+extern dec orderBy(target: Operation, property: valueof string, ...otherProperties: valueof string[]);
+
+/**
+ * `@pagedCollection` - mark a model as representing a paged collection.
+ *
+ * `@pagedCollection` can only be applied to models.
+ */
+extern dec pagedCollection(target: Model);
 
 /**
- * TODO: Enable this once Model type is supported. https://github.com/microsoft/typespec/issues/1655
+ * `@partial` - Mark a model as partial.
  *
+ * `@partial` can only be applied to models.
+ */
+extern dec partial(target: Model, value: Model);
+
+/**
  * `@privatePreview` - Allow us define a privatePreview element.
  * `@privatePreview` - Applies to models, model properties, enums, enum members, namespaces and operations.
-
+ */
 extern dec privatePreview(
   target: Model | ModelProperty | EnumMember | Enum | Operation | Namespace,
-  name: string
-)
- */
+  name: valueof string
+);
 
 /**
  * `@privatePreviewDefinition` - Allow us create a reusable private preview definition.
@@ -118,23 +212,25 @@ extern dec privatePreview(
  */
 extern dec privatePreviewDefinition(
   target: Namespace,
-  name: string,
-  announcementDate: string,
-  removalDate: string,
-  owner: string
+  name: valueof string,
+  announcementDate: valueof string,
+  removalDate: valueof string,
+  owner?: valueof string
 );
 
 /**
- * `@search` - Applies to: get operations that return collections.
- * Indicates that the get operation supports the OData $search query parameter.
+ * `@privileged` - mark the entity as privileged
+ *
+ * `@privileged` can be applied to Model, ModelProperty, Enum, EnumMember, Operation, Namespace.
  */
-extern dec search(target: Operation);
+extern dec privileged(target: Model | ModelProperty | Enum | EnumMember | Operation | Namespace);
 
 /**
- * `@skip` - Applies to: get operations that return collections.
- * Indicates that the get operation supports the OData $skip query parameter.
+ * `@publicNamespace` - defines the namespace to be used in generating CSDL output for all elements contained within the namespace
+ *
+ * `@publicNamespace` can only be applied to namespaces.
  */
-extern dec skip(target: Operation);
+extern dec publicNamespace(target: Namespace, name: valueof string);
 
 /**
  * `@readOnly` - mark a model property as readOnly property
@@ -150,6 +246,26 @@ extern dec readOnly(target: ModelProperty);
  */
 extern dec references(target: ModelProperty);
 
+/**
+ * `@requiredForCreate` - mark a model property as required when a request is made to
+ * Graph to create or update a resource.
+ *
+ * `@requiredForCreate` can only be applied to model properties.
+ */
+extern dec requiredForCreate(target: ModelProperty);
+
+/**
+ * `@search` - Applies to: get operations that return collections.
+ * Indicates that the get operation supports the OData $search query parameter.
+ */
+extern dec search(target: Operation);
+
+/**
+ * `@skip` - Applies to: get operations that return collections.
+ * Indicates that the get operation supports the OData $skip query parameter.
+ */
+extern dec skip(target: Operation);
+
 /**
  * `@top` - Applies to: get operations that return collections.
  * Indicates that the get operation supports the OData $top query parameter.
@@ -162,3 +278,30 @@ extern dec top(target: Operation);
  * `@writeOnly` can only be applied to model properties.
  */
 extern dec writeOnly(target: ModelProperty);
+
+/**
+* `@isOwner` - specify that this workload is the primary owner of this entity model
+*
+* `@isOwner` can be applied to Model where the model also has an @entity decorator or a ModelProperty where it has either an @contains or @references decorator.
+*/
+extern dec isOwner(target: Model | ModelProperty, value?: valueof boolean);
+
+/**
+ * `@workloadName` - specifies the name used by the underlying workload
+ *
+ * `@workloadName` can be applied to Model, ModelProperty, Enum, EnumMember.
+ */
+extern dec workloadName(
+  target: Model | ModelProperty | Enum | EnumMember,
+  workloadName: valueof string
+);
+
+/**
+ * `@workloadNameMsa` - specifies the name used by the underlying workload for consumer use cases
+ *
+ * `@workloadNameMsa` can be applied to Model, ModelProperty, Enum, EnumMember.
+ */
+extern dec workloadNameMsa(
+  target: Model | ModelProperty | Enum | EnumMember,
+  workloadNameMsa: valueof string
+);

package/lib/deployment.tsp

@@ -0,0 +1,18 @@
+namespace MsGraph.Deployment;
+
+enum deploymentTargets {
+  prodBeta,
+  prodV1_0,
+  prodEdu,
+  ppeBeta,
+  ppeV1_0,
+  ppeEdu,
+  mooncakeBeta,
+  mooncakeV1_0,
+  fairfaxBeta,
+  fairfaxV1_0,
+  usNatBeta,
+  usNatV1_0,
+  usSecBeta,
+  usSecV1_0
+}

package/lib/lib.tsp

@@ -1,35 +1,19 @@
 import "../dist/src/index.js";
-import "@typespec/rest";
+import "@typespec/http";
 
 using TypeSpec.Http;
-namespace TypeSpec.MsGraph;
+namespace MsGraph;
 
 scalar date;
 
 scalar stream;
 
-model ResourceResponse {}
+scalar guid extends string;
 
 model EmptyParameters {}
 
-model PagedListResponse {}
+// --- Base interfaces for all interfaces that contain operations returning entities.
 
-interface Item<T> {
-  @head _isOperation(@path id: string): T;
-}
+interface Resource<T> {}
 
-interface List<T> {
-  @head _isOperation(): T[];
-}
-
-interface Singleton<T> {
-  @head _isNavigationSource(@path id: string): T;
-}
-
-interface EntitySet<T> {
-  @head _isNavigationSource(): T[];
-}
-
-interface EntitySetResource<T> {
-  @head _isNavigationSource(@path id: string): T[];
-}
+interface Collection<T> {}

package/lib/msgraph.tsp

@@ -1,2 +1,6 @@
 import "./lib.tsp";
+import "./shared-models.tsp";
+// TODO: import "./deployment.tsp";
+import "./responses.tsp";
 import "./decorators.tsp";
+import "./porcelain.tsp";

package/lib/porcelain.tsp

@@ -0,0 +1,135 @@
+// -------------------------------------------------
+// porcelain.tsp
+// Operation templates to provide a much-simplified syntax for defining standard Graph operations.
+// -------------------------------------------------
+import "@typespec/http";
+import "./lib.tsp";
+import "./shared-models.tsp";
+import "./responses.tsp";
+
+using TypeSpec.Http;
+using MsGraph;
+using MsGraph.SharedModels;
+using MsGraph.Responses;
+
+namespace MsGraph;
+
+  namespace Foundations {
+
+    @doc("Foundational operations for individual resources and collections.")
+    interface GraphFoundations {
+      op Operation<TParams, TResponse, TErrorResponse>(
+        ...TParams
+      ): TResponse | TErrorResponse;
+
+      op ResourceOperation<
+        TResource extends {},
+        TParams,
+        TResponse,
+        TErrorResponse = ResourceErrorResponse
+      > is GraphFoundations.Operation<TParams, TResponse, TErrorResponse>;
+
+      op CollectionOperation<
+        TResource extends {},
+        TParams,
+        TResponse,
+        TErrorResponse = CollectionErrorResponse
+      > is GraphFoundations.Operation<TParams, TResponse, TErrorResponse>;
+    }
+  }
+
+  @doc("Primary operation shapes for Microsoft Graph")
+  interface GraphOps {
+
+    // TODO: This is how we should make $select standard for Graph.  Define a select decorator and use it here.
+    // @select("*") 
+    @get op GetCollection<
+    TResource extends {} = Automatic.CalculatedResourceType,
+    TParams =  {... Automatic.GraphRouteParams},
+    TResponse = CollectionResponse<TResource>,
+    TErrorResponse = CollectionErrorResponse
+    > is Foundations.GraphFoundations.CollectionOperation<
+      TResource, TParams, TResponse, TErrorResponse>;
+
+    // @select("*")
+    @get op GetPagedCollection<
+    TResource extends {} = Automatic.CalculatedResourceType,
+    TParams =  {... Automatic.GraphRouteParams},
+    TResponse = PagedCollectionResponse<TResource>,
+    TErrorResponse = CollectionErrorResponse
+    > is Foundations.GraphFoundations.CollectionOperation<
+      TResource, TParams, TResponse, TErrorResponse>;
+
+// TODO: GetDelta?  FUnction etc.?
+
+    // @select("*")
+    @post op Post<
+      TResource extends {} = Automatic.CalculatedResourceType,
+      TParams = { ... Automatic.GraphRouteParams, @body body: TResource },
+      TResponse = ResourceCreatedResponse<TResource>,
+      TErrorResponse = CollectionErrorResponse
+    > is Foundations.GraphFoundations.CollectionOperation<
+      TResource, TParams, TResponse, TErrorResponse>;
+        
+    // @select("*")
+    @get op GetResource<
+    TResource extends {} = Automatic.CalculatedResourceType,
+    TParams =  {... Automatic.GraphRouteParams},
+    TResponse = ResourceResponse<TResource>,
+    TErrorResponse = ResourceErrorResponse
+    > is Foundations.GraphFoundations.ResourceOperation<
+      TResource, TParams, TResponse, TErrorResponse>;
+
+    @delete op Delete<
+    TResource extends {} = Automatic.CalculatedResourceType,
+    TParams =  {... Automatic.GraphRouteParams},
+    TResponse = EmptyResponse,
+    TErrorResponse = ResourceErrorResponse
+    > is Foundations.GraphFoundations.ResourceOperation<
+      TResource, TParams, TResponse, TErrorResponse>;
+
+    @patch op PatchNoResponse<
+    TResource extends {} = Automatic.CalculatedResourceType,
+    TParams =  {... Automatic.GraphRouteParams},
+    TResponse = EmptyResponse,
+    TErrorResponse = ResourceErrorResponse
+    > is Foundations.GraphFoundations.ResourceOperation<
+      TResource, TParams, TResponse, TErrorResponse>;
+
+    // @select("*")
+    @patch op PatchWithResponse<
+    TResource extends {} = Automatic.CalculatedResourceType,
+    TParams =  {... Automatic.GraphRouteParams},
+    TResponse = ResourceResponse<TResource>,
+    TErrorResponse = ResourceErrorResponse
+    > is Foundations.GraphFoundations.ResourceOperation<
+      TResource, TParams, TResponse, TErrorResponse>;
+
+    @put op PutNoResponse<
+    TResource extends {} = Automatic.CalculatedResourceType,
+    TParams =  {... Automatic.GraphRouteParams},
+    TResponse = EmptyResponse,
+    TErrorResponse = ResourceErrorResponse
+    > is Foundations.GraphFoundations.ResourceOperation<
+      TResource, TParams, TResponse, TErrorResponse>;
+
+    // @select("*")
+    @put op PutWithResponse<
+    TResource extends {} = Automatic.CalculatedResourceType,
+    TParams =  {... Automatic.GraphRouteParams},
+    TResponse = ResourceResponse<TResource>,
+    TErrorResponse = ResourceErrorResponse
+    > is Foundations.GraphFoundations.ResourceOperation<
+      TResource, TParams, TResponse, TErrorResponse>;
+
+  }
+
+  namespace Automatic {
+    @doc("Marker type to allow injection of parameters from @route decorator.")
+    model GraphRouteParams { graphRouteParams: string }
+
+  // TODO: Needs direct support in the graphRoute decorator code to be able to make use of this.
+    @doc("Marker type to indicate to emitter that it should calculate resource from the Resource type of the containing interface's extended interface.")
+    model CalculatedResourceType {}
+  }
+

package/lib/responses.tsp

@@ -0,0 +1,82 @@
+// -------------------------------------------------
+// responses.tsp
+// Standard responses that Graph will return.
+// -------------------------------------------------
+import "@typespec/http";
+import "@microsoft/typespec-msgraph";
+import "./shared-models.tsp";
+
+using TypeSpec.Http;
+using MsGraph;
+using MsGraph.SharedModels;
+
+// Raw body models represent the content of the response body, without any additional metadata.
+// Note that these are primarily marker types.  CSDL has no notion of what actual body content is returned in such types,
+// but by passing markers through, HIDI can translate to OpenAPI.
+// The content of the types exists for other future emitters that run directly off TypeSpec.
+namespace MsGraph.Responses.Bodies {
+
+  @error
+  model ErrorBody {
+    error: publicError;
+  }
+
+  model ResourceBody<TResource> {
+   ...TResource;
+  }
+
+  model CollectionBody<TResource> {
+    value: TResource[];
+    `@odata.count`?: int64;
+  }
+
+  @pagedCollection
+  model PagedCollectionBody<TResource> is CollectionBody<TResource> {
+    `@odata.nextLink`?: MsGraph.SharedModels.url;
+  }
+
+  @pagedCollection
+  @deltaCollection
+  model DeltaCollectionBody<TResource> is PagedCollectionBody<TResource> {
+    `@odata.deltaLink`?: MsGraph.SharedModels.url;
+  }
+}
+
+// Response models represent the response as a whole, including the status code, headers, and body.
+namespace MsGraph.Responses {
+  @doc("Response to represent a Microsoft Graph collection response payload.")
+  model CollectionResponse<TResource, TStatus = 200, TBody = Bodies.CollectionBody<TResource>> 
+    is Http.Response<TStatus> {
+    ...Http.Body<TBody>;
+  }
+
+  @doc("Response to represent a Microsoft Graph paged collection response payload.")
+  model PagedCollectionResponse<TResource, TStatus = 200, TBody = Bodies.PagedCollectionBody<TResource>>
+    is CollectionResponse<TResource, TStatus, TBody>;
+
+  @doc("Response to represent a Microsoft Graph individual resource response payload.")
+  model ResourceResponse<TResource, TStatus = 200, TBody = Bodies.ResourceBody<TResource>>
+    is Http.Response<TStatus> {
+    ...Http.Body<TBody>;
+  }
+
+  @doc("Response to represent a Microsoft Graph resource creation response payload.")
+  model ResourceCreatedResponse<TResource, TStatus = 201, TBody = Bodies.ResourceBody<TResource>>
+    is ResourceResponse<TResource, TStatus, TBody> {
+    ...Http.LocationHeader
+  }
+
+  @doc("Response to represent a Microsoft Graph empty response payload.")
+  model EmptyResponse
+    is Http.Response<204>;
+  
+  @doc("Response to represent a Microsoft Graph error response payload.")
+  model ErrorResponse<TStatus>
+   is Http.Response<TStatus> {
+    ...Http.Body<Bodies.ErrorBody>;
+  }
+
+  alias ResourceErrorResponse = ErrorResponse<400 | 404 | 429>;
+  alias CollectionErrorResponse = ErrorResponse<400 | 429>;
+  
+}

package/lib/shared-models.tsp

@@ -0,0 +1,75 @@
+// -------------------------------------------------
+// shared-models.tsp
+// Common types shared among many workloads on Microsoft Graph
+// -------------------------------------------------
+import "@microsoft/typespec-msgraph";
+
+using MsGraph;
+
+@publicNamespace("microsoft.graph")
+namespace MsGraph.SharedModels;
+
+  // TODO: Spec how to deal with specified and unspecified ultimate base entities w.r.t. AGS runtime replacement policies. See #140
+  @doc("The primary entity base model for Microsoft Graph.")
+  @entity
+  model entity {
+    @key id: string;
+  }
+
+  @doc("Complex type to represent an identity principal by id, when a human-readable name is also useful.")
+  @complex
+  @open
+  model identity {
+    id: string;
+    displayName: string;
+  }
+
+  @doc("Complex type to represent a group of identity principals used at a point in time, such as createdBy, lastModifiedBy.")
+  @complex
+  @open
+  model identitySet {
+    user: identity | null;
+    device: identity | null;
+    application: identity | null;
+  }
+
+  @doc("Enum for identifying the format of a text string.")
+  enum bodyType {
+    text,
+    html
+  }
+
+  @doc("Complex type to represent a chunk of text that could be either plain text or html.")
+  @complex
+  model itemBody {
+    contentType: bodyType;
+    content: string;
+  }
+
+  @doc("Scalar type for URLs that would be expected to work in the browser address bar.")
+  scalar webUrl extends string;
+
+  @doc("Scalar type for URLs that represent Graph APIs.")
+  scalar url extends string;
+
+  @doc("Complex type to represent a nested error that potentially has other recursive nested errors.")
+  @complex
+  @open
+  model innerError {
+    code: string;
+    innererror: innerError | null;
+  }
+
+  @doc("""
+  Complex type to represent a standard Microsoft Graph error.
+  {code}: The error code.
+  """)
+  @complex
+  @error
+  model publicError {
+    code: string;
+    message: string;
+    target: string | null;
+    innererror: innerError | null;
+    details: publicError[];
+  }