Java Folder Structure

Context and Problem Statement

A port of the Semantic Kernel to Java is under development in the experimental-java branch. The folder structure being used has diverged from the .Net implementation. The purpose of this ADR is to document the folder structure that will be used by the Java port to make it clear to developers how to navigate between the .Net and Java implementations.

Decision Drivers

• Goal is to learn for SDKs that already have excellent multiple language support e.g., Azure SDK
• The Java SK should follow the general design guidelines and conventions of Java. It should feel natural to a Java developer.
• Different language versions should be consistent with the .Net implementation. In cases of conflict, consistency with Java conventions is the highest priority.
• The SK for Java and .Net should feel like a single product developed by a single team.
• There should be feature parity between Java and .Net. Feature status must be tracked in the FEATURE_MATRIX

Considered Options

Below is a comparison of .Net and Java Folder structures

dotnet/src
           Connectors
           Extensions
           IntegrationTests
           InternalUtilities
           SemanticKernel.Abstractions
           SemanticKernel.MetaPackage
           SemanticKernel.UnitTests
           SemanticKernel
           Skills

Some observations:

• The src folder is at the very start of the folder structure, which reduces flexibility
• The use of the Skills term is due to change

java
     api-test
     samples
     semantickernel-api
     semantickernel-bom
     semantickernel-connectors-parent
     semantickernel-core-skills
     semantickernel-core
     semantickernel-extensions-parent

Some observations:

• Using lowercase folder name with the - delimiter is idiomatic Java
• The src folders are located as close as possible to the source files e.g., semantickernel-api/src/main/java, this is idiomatic Java
• Unit tests are contained together with the implementation
• The samples are located within the java folder and each sample runs standalone

Decision Outcome

Follow these guidelines:

• The folder names will match those used (or planned for .Net) but in the idiomatic Java folder naming convention
• Use bom instead of MetaPackage as the latter is .Net centric
• Use api instead of Abstractions as the latter is .Net centric
• Move semantickernel-core-skills to a new plugins folder and rename to plugins-core
• Use the term plugins instead of skills and avoid introducing technical debt