Deprecate use of the string name field in favour of AppMetadata

[kriswest]

Enhancement Request

In FDC3 1.2 we introduced the TargetApp type:

type TargetApp = string | AppMetadata;

to help us transition from using the string name field in several places (intent resolutions, targeted raisedIntents etc.) to using the AppMetadata type. Its also been suggested that we should be encouraging users of the API to use the full AppMetadata Object returned by another call (e.g. findIntent, raiseIntent's IntentResolution).

Should we:

• deprecate the use of the name field alone
• formally encourage Desktop Agent implementations to return AppMetadata rather than name (e.g. in IntentResolution's source field via the application if the SHOULD keyword in the spec)
• provide clear advice and examples of using the AppMetadata objects in the spec and documentation.

n.b. name was not deprecated when TargetApp/AppMetadata use was introduced - that should happen before its removed, despite the fact that our next version is a major release.

[kriswest]

@pbaize I've raised this issue in response to your recent comments on this topic + my own feelings on the inelegance of the name field (when AppD supports multiple apps with the same name). Hence, your input would be appreciated.

[pbaize]

I'm in full agreement here.

I'd even go as far as asking whether we should release one more 1.x version for deprecations.

[kriswest]

As per comment in discussion #678:
#678 (reply in thread)

The proposed changes are:

• AppMetadata's name field goes from required to optional and appId from optional to required:

interface AppMetadata {
  name: string;
  appId?: string;
  version?: string;
  title?: string;
  ... etc.
}

changes to:

interface AppMetadata {
  appId: string;
  name?: string;
  version?: string;
  title?: string;
  ... etc.
}

• We would then drop the type TargetApp type, which is just string | AppMetadata and helps us avoid duplicate function signatures currently, and split the function signatures up, with the versions using name becoming deprecated. I.e.:

interface DesktopAgent {
  // apps
  open(app: TargetApp, context?: Context): Promise<void>;
  ...
  // intents
  ...
  raiseIntent(intent: string, context: Context, app?: TargetApp): Promise<IntentResolution>;
  raiseIntentForContext(context: Context, app?: TargetApp): Promise<IntentResolution>;
  ...
}

changes to:

interface DesktopAgent {
  // apps
  open(app: AppMetadata, context?: Context): Promise<void>;
  ...
  
  // intents
  ...
  raiseIntent(intent: string, context: Context, app?: AppMetadata): Promise<IntentResolution>;
  raiseIntentForContext(context: Context, app?: AppMetadata): Promise<IntentResolution>;
  ...

  //deprecated
  open(name: String, context?: Context): Promise<void>;
  raiseIntent(intent: string, context: Context, name?: String): Promise<IntentResolution>;
  raiseIntentForContext(context: Context, name?: String): Promise<IntentResolution>;
}

[thorsent]

Per today's discussion, I'd like to suggest that we break AppMetadata down:

AppIdentifier : {
   appId: string;
   instanceId ?: srtring
}

AppMetadata = AppIdentifier & {
   version ?: string;
   ...
}

This then allows inbound function signatures to accept AppIdentifier while outbound can deliver AppMetadata - but the AppMetadata can still be passed around the way Pierre had originally suggested.